Logg innBestill en gjennomgang

Kapittel 2.28

Utgi utvidelsen din

Hvordan en plugin eller pakke går fra et grønt bygg til enhetene som kjører den, og hvordan den tas ut igjen. Versjoner, utgivelsesgjennomgang, kanaler og installasjoner, signering, endringsgodkjenninger, oppføringen for leveringsidentitet, migreringer, tilbakerulling og utfasing av en versjon.

Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

18 minutter å lese

Cold chain 0.4.0 var den første utgivelsen vår som ba om mer enn den forrige. Den la til sending av e-post og én ekstern adresse, for varsler om kjølecontainere. Bygget var grønt, testene besto på alle tre syntetiske avdelinger, og likevel ble den liggende i utviklingsområdet i to dager mens to personer leste hva den ba om, og en tredje godkjente adressen. Slik skal det kjennes å gi ut på Nexus: koden er den enkle delen, og dokumentasjonen og godkjenningene er selve utgivelsen.

Dette kapitlet dekker alt mellom et grønt bygg og en versjon som kjører for alle enheter, og veiene tilbake. Selve forfremmelsesløpet, fra utviklingsområde til staging til en pilotenhet til alle enheter, introduseres i kapittel 2.24, Bygge en tilpasset vertikal fra start til slutt, og jeg gjentar ikke portene her. Én regel rammer inn alt sammen. Utrulling skjer kun gjennom installasjonens utgivelseskanaler. Det finnes ingen bakdør for en hastefiks, og ingen redigerer et kjørende image for hånd.

Versjoner

Tre versjonsnumre endres i en pakkeutgivelse, og det lønner seg å holde dem atskilt i hodet.

Hva Hvor den ligger Eksempel Regel
Pluginen version i nexus.manifest.json 0.4.0 Semantisk versjon; et forhåndsutgivelsessuffiks som -rc.1 er tillatt
Pakken version i pack.json 0.4.0 Endres sammen med pakkens linser, ord og klynger
Kunnskapsmodellen Modellens egen versjon 1.3 til 1.4 Endres kun gjennom en endringsforespørsel for grafen

Et utviklingsbygg har et suffiks, 0.4.0-dev, til det når staging. Hold plugin- og pakkeversjonene like når de leveres sammen; det sparer en diskusjon i hver utgivelsesgjennomgang om hvilket nummer dokumentasjonen gjelder.

To andre versjoner er låst i stedet for valgt. Pakkens malversjon (domain-pack@1.6.0 for Cold chain) fastsettes når pakken lages, og endres kun som en gjennomgått endring. SDK-en (programvareutviklingssettet) installeres i en eksakt versjon, aldri et intervall, slik at det samme bygget gir det samme resultatet neste måned:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

Ferdigheter i Skills Engine har også versjoner, og de oppfører seg annerledes. Hver publiserte versjon er låst, og live, canary og shadow er etiketter på versjoner. Å bytte tilbake flytter en etikett, og kjøringer som allerede pågår, fullføres på versjonen de startet med.

Før du ber om gjennomgang: manifestet

Siden Manifest og tillatelser sammenligner hva denne utgivelsen deklarerer, med forrige utgivelse: omfang, lagre, utgående adresser og sandkasseprofil. Les den før du ber noen om gjennomgang, fordi den viser nøyaktig hva gjennomgåerne vil bli bedt om å godta.

Manifest og tillatelser
Manifest og tillatelser
Hva Cold chain 0.4.0 deklarerer sammenlignet med 0.3.2. Legg merke til de to linjene som er merket som utvidelser, sending av e-post og én ekstern adresse, og skiltet som sier at utgivelsen ikke går videre fra utviklingsområdet før to gjennomgåere godtar dem.

En utgivelse som ber om mer enn manifestet tidligere deklarerte, holdes der den er, med MANIFEST_SCOPE_WIDENED, til to gjennomgåere godtar det utvidede manifestet. En ekstern adresse krever i tillegg godkjenning fra den som eier eksterne adresser hos kunden; den godkjenningen gis for en fast periode, og vår gjaldt i 12 måneder. Du har to veier videre: fjerne linjene eller be om gjennomgang. Siden tilbyr begge knappene.

Hver linje på den siden håndheves ved kjøretid, ikke bare ved gjennomgang. Hvert verktøykall kontrolleres mot de deklarerte omfangene, en ekstern adresse blokkeres med mindre den er oppført, og sandkasseprofilen tillater ikke noe annet nettverk. En plugin som prøver å nå noe den ikke har deklarert, avvises, og den eneste løsningen er en ny utgivelse som deklarerer det.

Utgivelsesgjennomgang

Siden Utgivelsesgjennomgang samler dokumentasjonen for én utgivelse i én tabell, for en gjennomgåer som ikke er forfatteren.

Utgivelsesgjennomgang
Utgivelsesgjennomgang
En annen gjennomgåers visning av Cold chain 0.4.0, med dokumentasjonstabellen, omfangsforskjellen og kommentarene. Legg merke til skiltet til høyre: forfatteren kan ikke godkjenne sin egen utgivelse.
Dokumentasjon Hva den viste for 0.4.0
Tester 66 av 66, på tre syntetiske avdelinger
Kvalitetskontroller Dokumentasjonen og koden stemmer overens
Policy Hver linse bare innsnevrer; personopplysningsfelt er av som standard
Signaturer Image og pakke signert av pipelinen
Omfangsforskjell Legger til sending av e-post og én ekstern adresse, med tilhørende godkjenning
Kompatibilitet Plattformversjonen og basispakkeversjonen den ble testet mot
Modellendring Prøvekjøringen av endringsforespørselen for grafen: 1 284 koblinger omdøpt, ingenting fjernet

Under tabellen ligger kommentarene til endringen og opprinnelsen: hvilken pipeline som bygde den, fra hvilken endring, image-digesten og malen. Gjennomgåere godkjenner med passnøkkelen sin. To gjennomgåere som ikke er forfatteren, godkjenner, og pipelinen flytter deretter utgivelsen til staging. Forfatteren teller aldri som gjennomgåer, og et forsøk avvises med NEEDS_SECOND_PERSON. En forespørsel om gjennomgang utløper etter 3 dager.

Svar på gjennomgåernes spørsmål i kommentarene, ikke i et chattevindu. Under vår gjennomgang spurte samsvarsansvarlig hvorfor kravbeløp var klassifisert som kommersielt, og den andre gjennomgåeren ba om tilbakerullingsplanen for modellendringen. Begge svarene er nå en del av utgivelsens historikk, der neste gjennomgåer vil lete.

Godkjenninger etter endringspolicy

Utgivelsesgjennomgangen dekker utgivelsen som helhet. changePolicy-blokken i manifestet går lenger: den angir hvilke klasser av endringer i pluginens leveranseenheter som krever godkjenning, og fra hvor mange personer.

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

De tre klassene er website (webappen), bff (backend for frontend) og migration (en databasemigrering). Hver klasse som er oppført i classes, må ha sitt eget antall i approvals, fra 1 til 10. En klasse du utelater, er ustyrt, og skjemaet tvinger deg til å skrive det som et valg i stedet for å havne der ved utelatelse. Vi krever to godkjenninger for migreringer fordi en migrering er den ene endringen som er vanskelig å reversere.

Godkjenninger telles i distinkte personer, og forslagsstilleren er aldri en av dem. Reglene som understøtter dette, er verdt å kjenne, fordi hver av dem har en avvisning:

  • En godkjenning fra personen som foreslo endringen, avvises med TRUST_APPROVAL_SELF_APPROVAL.
  • En person som overhodet ikke har lov til å gjøre en endring av den klassen, avvises med CHANGE_CLASS_NOT_PERMITTED.
  • Når en commit i endringen er signert av organisasjonens agentidentitet, er quorumet det vanlige minimumet pluss én, og agentens egen stemme teller ikke.
  • Hver godkjenning registrerer diffen og head-revisjonen den så. Hvis endringen flytter seg etter siste godkjenning, avvises sammenslåingen med HASH_MISMATCH, og godkjenningene må innhentes på nytt for det nye innholdet.

Den tredje regelen er viktig hvis du bygger med et KI-kodeverktøy (kunstig intelligens), slik kapittel 2.26, Bygge med KI-kodeverktøy, beskriver. Arbeid som en agent har skrevet, krever én menneskelig godkjenning mer enn arbeid en person har skrevet. Planlegg for det.

Signering og verifisering

Hvert image og hver pakke signeres av pipelinen som bygde dem, og et signert image er en av portene inn til staging. Et utviklingsområde kjører kun signerte images fra starten av. På Enterprise setter en administrator hvert navnerom til enten å registrere usignerte images eller å avvise dem, og flytter navnerom over til avvisning ett om gangen, slik at produksjon til slutt kun kjører images som pipelinen har bygd og signert. Signering er en del av bygget, ikke noe du legger til før en utgivelse.

Regelen som går gjennom alt dette, er at en signatur som feiler, er en avvisning, aldri en advarsel. En kontroll som mottar SIG_INVALID, stopper. Den faller ikke tilbake til den usignerte versjonen, og den fortsetter ikke med en merknad i en logg, fordi en advarsel i en byggelogg er en godkjenning for alle som ikke leste den.

Den samme regelen gjelder alt du overleverer på medier. En forseglet pakke for en kunde uten nettverkstilkobling verifiseres mot din offentlige nøkkel før noe pakkes ut, og kapittel 2.25, Bygge for hver utgave, viser kommandoen.

Leveringsidentitet

En plugin leveres gjennom flere ting som hver har et navn: repositoriene, en signeringsnøkkel, et utrullingsnavnerom, et registerprefiks, et databaseskjema, et sett med domener og en endringspolicy. Hver av dem er et sted der to plugins kan kollidere, eller én plugin kan drive. Leveranseidentiteten er én signert post per plugin som inneholder alle, slik at hver kontroll i utgivelsesløpet leser det samme svaret og avviser ved avvik.

Du bidrar med din del gjennom manifestet og ingenting annet: schema, db, domains, changePolicy og repositoriets URL. Plattformen fullfører posten med resten og signerer den. Du navngir aldri ditt eget navnerom, registerprefiks eller din egen signeringsnøkkel. De tildeles deg, og et manifest som forsøkte å deklarere dem, ville fremsette en påstand som kontrollene da måtte avvise.

Den signerte posten inneholder elleve felt: pluginens slug, organisasjonen som eier den, organisasjonen som bygger den, repositoriene, navnet på signeringsnøkkelen, utrullingsnavnerommet, registerprefikset, databaseskjemaet, domenene, endringspolicyen og en kort liste over eldre image-navn den brukte før registerprefikset fantes. Den siste listen kan bare krympe. Fordi den er signert, kan en ny signatur fjerne en oppføring, og ingenting kan legge til en i det stille. Signaturen er Ed25519 over den standard kanoniske JSON-formen av disse elleve feltene, slik at en post med «Tomás» eller «Sinéad» i seg verifiseres likt overalt.

Når en utgivelse ikke samsvarer med posten sin, gjelder den første avvisningen:

Kode Når HTTP
DELIVERY_IDENTITY_MISSING Det finnes ingen post for pluginen 403
DELIVERY_PATH_REFUSED En image-push utenfor registerprefikset som ikke står på den signerte listen over eldre navn 403
NAMESPACE_MISMATCH En utrulling rettet mot et annet navnerom 403
IMAGE_NAME_COLLISION Et image-navn som en annen plugin allerede gjør krav på 409
CHANGE_CLASS_NOT_PERMITTED En endringsklasse som policyen ikke styrer 403

IMAGE_NAME_COLLISION er den som overrasker folk. Velg et annet navn, og gjenbruk aldri et: et delt image-navn betyr at én plugins forfremmelse kan flytte en annen plugins poder.

Migreringer, committet og avgrenset

En migrering leveres i pluginens image og kjøres før den nye versjonen starter, gjennom SDK-ens ene migreringskjører, nexus-migrate. Du skriver ikke din egen applikator. Før en utgivelse kan flyttes, kjører den samme kjøreren migreringene dine én fil om gangen mot en engangsdatabase, slik at en migrering som feiler, feiler der. Malens skyggebygg kaller kjøreren én gang per fil, i rekkefølge, og registrerer hver fil slik produksjon vil gjøre.

Kjørerens regler er de samme som portene kontrollerer, skrevet som kode:

  1. Den kobler til som skjemaets migratorrolle og kjører hver fil som skjemaets eier. Enhver annen pålogging, en superbruker fremfor alt, avvises. En fil som selv forsøker å bytte rolle, avvises før noe kjøres.
  2. Leietakerfilen, nummerert 0, redigeres aldri etter at den er kjørt. En endring i leietakeroppsettet får sin egen revisjonsfil, 000_tenancy_r<N>.sql, som nexus-tenancy render --revision <N> skriver for deg.
  3. Normalt eier kjøreren hver fils transaksjon og avviser en BEGIN eller COMMIT inne i den. En fil som håndterer sine egne transaksjoner, deklarerer at den kjøres per setning, og da må hver BEGIN den åpner, ha en motpart.
  4. Den fører en logg, én rad per fil, med filens SHA-256 og hvordan den ble kjørt. En kjørt fil endres aldri på stedet; en endring er en ny nummerert fil.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Avgrenset betyr at hver ny tabell har organization_id, owner_user_id og business_unit_id, pluss markørkolonnen is_demo med mindre gates/demo-exempt.json unntar tabellen med en begrunnelse, med en primærnøkkel som starter med organisasjonen og fremmednøkler som bærer den, og med påtvunget sikkerhet på radnivå. Porten migrations-are-scoped kontrollerer disse reglene i hver fil, og migrations-commit-what-they-open teller at hver fil committer det den åpner. Den andre porten finnes fordi en migrering som stille ble rullet tilbake, en gang avsluttet med 0, og tabellen den skulle ha opprettet, fantes aldri.

Én fil til hører med i hver utgivelse. scripts/ci/required-env skriver ut miljøvariablene tjenesten din trenger for å starte, som en JSON-matrise hentet fra konfigurasjonslasteren din. Utgivelsesløpet kjører den og avviser en utgivelse der utrullingen ikke setter hver eneste av dem, slik at en manglende variabel fanges opp før utgivelsen, ikke av en pod som ikke vil starte.

node scripts/ci/required-env

Utgi ferdigheter

De to typene ferdigheter når folk via ulike veier, så gi dem ut på ulike måter.

En manifestferdighet, en typet rad i pluginens skills[], leveres med pluginen og går gjennom den samme forfremmelsen som resten av den. Onboarding synkroniserer hele ferdighetssettet til registeret ved hver utgivelse. Utelater du en ferdighet fra settet, deaktiveres den, og på Enterprise tar en synkronisering med én feilaktig ferdighet ingen av dem, slik at den forrige versjonen fortsetter å kjøre i stedet for halvparten av den nye.

En Skills Engine-ferdighet publiseres fra biblioteket. På Enterprise venter en ferdighet som legger til et skriveverktøy, på at to navngitte personer godkjenner den med passnøklene sine, og den som foreslår den, kan ikke være en av dem. En godkjent versjon kjører deretter i skyggemodus, så som canary for én enhet bak navngitte porter, deretter for alle, og den stopper seg selv hvis en port ikke oppfylles. Hvis programtillegget Deres og en Skills Engine-ferdighet er avhengige av hverandre, publiserer De ferdigheten først og lar den nå alle før utgivelsen av programtillegget som kaller den, forlater piloten.

Kanaler og installasjoner

Når en utgivelse har bestått piloten og nådd alle enheter, tilbys den på en kanal, og hver enhet velger sin kanal. Enhetens administrator samtykker til hver overgang. Siden Kanaler og installasjoner viser hvilke enheter som kjører hvilken versjon, med feilrater kun som antall: De ser hvordan utvidelsen Deres oppfører seg, aldri hva noen har gjort med den.

Kanaler og installasjoner
Kanaler og installasjoner
Hvilke enheter som kjører hvilken versjon av carrier-sync, med en tilbakerulling åpen for én enhet. Legg merke til hva dialogboksen sier endres, hva som forblir, og at den krever en annen person, enhetens egen administrator.

Vårt carrier-sync-programtillegg kjører tre versjoner samtidig, og det er normalt. De fleste enheter er på gjeldende utgivelse, én enhet blir værende på en eldre versjon på en kanal som opprettholdes til en angitt dato, og en utgivelseskandidat ligger på en kanal som ingen har valgt ennå. Ikke kjemp imot det; en enhet som trenger stabilitet for en revisjon, har krav på det.

Utvidelsens logger og måledata

Siden for logger og måledata for pakken Deres er låst til Deres egne arbeidslaster, i de enhetene der De har tilgang til å se. De kan filtrere etter enhet og miljø, og De ser antall, tidsbruk og tilstander.

Pakkens logger og måledata
Pakkens logger og måledata
Cold chains egne logger og måledata, filtrert til Rotterdam-piloten. Se på logglinjene: personen som rapporterte et avvik, er skjult, og teksten i kravnotatet blir aldri logget i det hele tatt.

Personopplysningsfelt erstattes før en linje skrives, og kundeinnhold som kravtekst, e-post eller dokumentinnhold skrives aldri til logger. Logger oppbevares i 14 dager. Organisasjonen fastsettes av gatewayen, aldri av spørringen Deres, så en spørring som navngir en annen organisasjon, avvises med TENANT_BOUNDARY. Assistenten i dokken kan lese de samme loggene sammen med Dem, og bare disse: Da jeg spurte den hvorfor avviksposter kom inn sent én morgen, sporet den 18 minutter med nye forsøk tilbake til dupliserte målinger fra strømforsyningen til én kai.

Rulle tilbake

Det finnes to typer tilbakerulling, og begge er gjennomgåtte endringer snarere enn brytere.

Tilbakerulling av et miljø bruker den forrige versjonen. Hvert miljø beholder den i 30 dager. Tilbakerullingen klargjøres som en endring av utgivelsen, forhåndsviser hva den vil gjøre og krever en annen person; når den er godkjent, ruller pipelinen tilbake på omtrent ett minutt. Hver tilbakerulling tidtas, og det samme gjør hver øvelse, så øv på én før De trenger det. Tilbakerulling av én enhet gjøres via siden Kanaler og installasjoner. Dialogboksen for tilbakerulling oppgir hva som endres (den enheten kjører den eldre versjonen igjen, og feilraten overvåkes i én time), hva som forblir (de andre enhetene, og enhetens innstillinger og poster), begrunnelsen, og hvem den andre personen er: den enhetens administrator.

Innstillinger og poster beholdes ved en tilbakerulling, så planlegg hver utgivelse ut fra at den forrige versjonen kan komme til å kjøre igjen på dataene som den nyere versjonen skrev. Det er den praktiske grunnen til å holde migreringer additive innenfor en utgivelse De kan komme til å rulle tilbake, og grunnen til at vi ber to personer godkjenne hver av dem. En modellendring er det samme: En gjennomgåer kan, og bør, be om tilbakerullingsplanen for en endringsforespørsel for grafen før den godkjennes.

Ferdigheter rulles tilbake mer skånsomt. Å flytte live-etiketten tilbake til en tidligere versjon er ett steg, og kjøringer som allerede pågår, fullføres på versjonen de startet med.

Fase ut en versjon

En utgivelse blir aldri redigert når den først er laget. En versjon som ikke lenger skal brukes, trekkes tilbake, og en rettelse leveres som et nytt versjonsnummer. SDK-ets egne utgivelseskanaler følger samme praksis: En dårlig SDK-versjon trekkes, og erstattes aldri med annet innhold under samme nummer. Gjør det samme, for et versjonsnummer som kan bety to forskjellige bygg, gjør alt bevis om det verdiløst.

Tilbaketrekking av et programtillegg eller en pakke stopper nye installasjoner. Enhetene beholder versjonen de kjører til de bytter, så tilbaketrekking er et signal og en frist, ikke en avbryter. Fortell enhetsadministratorene hvilken versjon de skal bytte til, og innen når.

Avvikling av en ferdighet følger samme idé med ett steg til. Skills Engine flytter alle gjenværende kallere til en erstatning etter å ha kjørt erstatningens testtilfeller, stopper nye kjøringer og beholder versjonene, testtilfellene og de forseglede kjøringspostene, slik at ferdigheten kan hentes tilbake hvis erstatningen viser seg å være feil.

En sjekkliste for utgivelse

Dette er listen vi leser før hver Cold chain-utgivelse. Den er kort fordi plattformen kontrollerer det meste av den for oss.

  1. Versjonene samsvarer: manifestet, pack.json og kunnskapsmodellen hvis den er endret.
  2. Hver port er grønn lokalt, fra rent utgangspunkt, og hver ny test er vist å feile først.
  3. Siden Manifest og tillatelser viser ingen utvidelse, eller utvidelsen er tilsiktet og gjennomgåerne vet hvorfor.
  4. Hver migrering er en ny nummerert fil, avgrenset og anvendt uten feil mot en engangsdatabase.
  5. scripts/ci/required-env lister opp hver variabel tjenesten trenger, og utrullingen angir hver av dem.
  6. Tilbakerullingsplanen er skrevet i endringen, også for enhver modellendring.
  7. To gjennomgåere som ikke er forfatteren, er tilgjengelige denne uken.

Det siste punktet høres trivielt ut. Det er det som har forsinket flere av utgivelsene våre enn alle portene til sammen.