Log indBook en briefing

Kapitel 2.28

Udgivelse af jeres udvidelse

Hvordan et plugin eller en pakke går fra et godkendt build til de enheder, der kører det, og hvordan det tages ud igen. Versioner, udgivelsesgennemgang, kanaler og installationer, signering, ændringsgodkendelser, registrering af leveringsidentitet, migreringer, tilbagerulning og udfasning af en version.

Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

18 minutters læsetid

Cold chain 0.4.0 var vores første udgivelse, der bad om mere end den foregående. Den tilføjede afsendelse af mail og én ekstern adresse til alarmer for kølecontainere. Buildet var grønt, og testene bestod på alle tre syntetiske filialer. Alligevel blev den liggende i udviklingsrummet i to dage, mens to personer læste, hvad den bad om, og en tredje godkendte adressen. Sådan er det meningen, at en udgivelse på Nexus skal føles: koden er den lette del, og dokumentationen og godkendelserne er selve udgivelsen.

Dette kapitel dækker alt mellem et grønt build og en version, der kører for alle enheder, samt vejene tilbage igen. Selve forfremmelsesvejen fra udviklingsrum til staging, til en pilotenhed og til alle enheder introduceres i kapitel 2.24, Opbygning af en tilpasset vertikal fra ende til anden, og jeg gentager ikke dens kontrolpunkter her. Én regel rammer det hele ind. Udrulning sker udelukkende gennem installationens udgivelseskanaler. Der findes ingen bagdør til en hastende rettelse, og ingen redigerer et kørende image manuelt.

Versioner

Tre versionsnumre ændres i en pakkeudgivelse, og det betaler sig at holde dem adskilt i hovedet.

Hvad Hvor det findes Eksempel Regel
Pluginet version i nexus.manifest.json 0.4.0 Semantisk version; et pre-release-suffiks som -rc.1 er tilladt
Pakken version i pack.json 0.4.0 Ændres med pakkens linser, ord og klynger
Vidensmodellen Modellens egen version 1.3 til 1.4 Ændres kun gennem en ændringsanmodning for grafen

Et udviklingsbuild har et suffiks, 0.4.0-dev, indtil det når staging. Hold plugin- og pakkeversionerne ens, når de leveres sammen; det sparer Dem for en diskussion ved hver udgivelsesgennemgang om, hvilket nummer dokumentationen hører til.

To andre versioner er fastlåste frem for valgte. Pakkens skabelonversion (domain-pack@1.6.0 for Cold chain) fastlægges, når pakken oprettes, og ændres kun som en gennemgået ændring. SDK'et (software development kit) installeres i en præcis version, aldrig et interval, så det samme build giver det samme resultat næste måned:

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

Skills Engine-færdigheder har også versioner, og de opfører sig anderledes. Hver udgivet version er fastlåst, og live, canary og shadow er etiketter på versioner. At skifte tilbage flytter en etiket, og kørsler, der allerede er i gang, afsluttes på den version, de startede med.

Før I anmoder om gennemgang: manifestet

Siden Manifest og tilladelser sammenligner, hvad denne udgivelse erklærer, med den seneste udgivelse: dens scopes, dens lagre, dens udgående adresser og dens sandbox-profil. Læs den, før De beder nogen om en gennemgang, for den viser Dem præcis, hvad gennemlæserne vil blive bedt om at acceptere.

Manifest og tilladelser
Manifest og tilladelser
Hvad Cold chain 0.4.0 erklærer i forhold til 0.3.2. Bemærk de to linjer, der er markeret som udvidelser, afsendelse af mail og én ekstern adresse, samt pladen, der siger, at udgivelsen ikke kommer videre end udviklingsrummet, før to gennemlæsere accepterer dem.

En udgivelse, der beder om mere, end dens manifest tidligere erklærede, holdes tilbage, hvor den er, med MANIFEST_SCOPE_WIDENED, indtil to gennemlæsere accepterer det udvidede manifest. En ekstern adresse kræver desuden godkendelse fra den person hos kunden, der ejer eksterne adresser; denne godkendelse gives for en fast periode, og vores gjaldt i 12 måneder. De har to veje frem: fjern linjerne, eller anmod om en gennemgang. Siden tilbyder begge knapper.

Hver linje på siden håndhæves under kørsel, ikke kun ved gennemgang. Hvert værktøjskald kontrolleres mod de erklærede scopes, en ekstern adresse blokeres, medmindre den er angivet, og sandbox-profilen tillader intet andet netværk. Et plugin, der forsøger at nå noget, det ikke har erklæret, afvises, og den eneste løsning er en ny udgivelse, der erklærer det.

Udgivelsesgennemgang

Siden Udgivelsesgennemgang samler dokumentationen for én udgivelse i én tabel til en gennemlæser, der ikke er forfatteren.

Udgivelsesgennemgang
Udgivelsesgennemgang
En anden gennemlæsers visning af Cold chain 0.4.0 med dokumentationstabellen, scope-forskellen og kommentarerne. Bemærk pladen til højre: forfatteren kan ikke godkende sin egen udgivelse.
Dokumentation Hvad den viste for 0.4.0
Tests 66 af 66 på tre syntetiske filialer
Kvalitetskontroller Dokumentationen og koden stemmer overens
Politik Hver linse indsnævrer kun; personfelter er som standard slået fra
Signaturer Image og pakke signeret af pipelinen
Scope-forskel Tilføjer afsendelse af mail og én ekstern adresse med tilhørende godkendelse
Kompatibilitet Platformversionen og den basispakkeversion, den blev testet mod
Modelændring Prøvekørslen af ændringsanmodningen for grafen: 1.284 links omdøbt, intet fjernet

Under tabellen findes kommentarerne til ændringen og oprindelsen: hvilken pipeline der byggede den, ud fra hvilken ændring, image-digesten og skabelonen. Gennemlæsere godkender med deres passkey. To gennemlæsere, der ikke er forfatteren, godkender, og pipelinen flytter derefter udgivelsen til staging. Forfatteren tæller aldrig som gennemlæser, og et forsøg afvises med NEEDS_SECOND_PERSON. En anmodning om gennemgang bortfalder efter 3 dage.

Besvar gennemlæsernes spørgsmål i kommentarerne, ikke i et chatvindue. Under vores gennemgang spurgte vores compliance-ansvarlige, hvorfor skadesbeløb var klassificeret som kommercielt, og den anden gennemlæser bad om tilbagerulningsplanen for modelændringen. Begge svar indgår nu i udgivelsens historik, og det er dér, den næste gennemlæser vil kigge.

Godkendelser i henhold til ændringspolitik

Udgivelsesgennemgangen dækker udgivelsen som helhed. Blokken changePolicy i manifestet går videre: den angiver, hvilke klasser af ændringer i Deres plugins udrulbare komponenter der kræver godkendelse, og fra hvor mange personer.

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

De tre klasser er website (webappen), bff (backend for frontend) og migration (en databasemigrering). Hver klasse, der er nævnt i classes, skal have sit eget antal i approvals, fra 1 til 10. En klasse, De udelader, er ustyret, og skemaet tvinger Dem til at skrive det som et valg frem for at nå dertil ved en udeladelse. Vi kræver to godkendelser for migreringer, fordi en migrering er den ene ændring, der er svær at gøre om.

Godkendelser tælles i forskellige personer, og den, der foreslår ændringen, er aldrig en af dem. Reglerne, der understøtter dette, er værd at kende, fordi hver af dem har en afvisning:

  • En godkendelse fra den person, der foreslog ændringen, afvises med TRUST_APPROVAL_SELF_APPROVAL.
  • En person, der slet ikke må foretage en ændring af den klasse, afvises med CHANGE_CLASS_NOT_PERMITTED.
  • Når en commit i ændringen er signeret af organisationens agentidentitet, er kvorummet det sædvanlige minimum plus én, og agentens egen stemme tæller ikke.
  • Hver godkendelse registrerer den diff og det head, den så. Hvis ændringen flytter sig efter den sidste godkendelse, afvises sammenfletningen med HASH_MISMATCH, og godkendelserne skal indhentes igen for det nye indhold.

Den tredje regel har betydning, hvis De bygger med et AI-kodeværktøj (kunstig intelligens), som beskrevet i kapitel 2.26, Bygning med AI-kodeværktøjer. Arbejde, som en agent har skrevet, kræver én menneskelig godkendelse mere end arbejde, som en person har skrevet. Planlæg efter det.

Signering og verifikation

Hvert image og hver pakke signeres af den pipeline, der byggede dem, og et signeret image er et af kontrolpunkterne ind i staging. Et udviklingsrum kører kun signerede images fra starten. På Enterprise indstiller en administrator hvert namespace til enten at registrere usignerede images eller afvise dem og flytter namespaces over til afvisning ét ad gangen, så produktionen ender med kun at køre images, som pipelinen har bygget og signeret. Signering er en del af buildet, ikke noget, De tilføjer før en udgivelse.

Reglen, der går igen i det hele, er, at en signatur, der fejler, er en afvisning, aldrig en advarsel. En kontrol, der modtager SIG_INVALID, stopper. Den falder ikke tilbage til den usignerede version, og den fortsætter ikke med en note i en log, for en advarsel i en buildlog er en godkendelse for alle, der ikke læste den.

Den samme regel gælder for alt, hvad De udleverer på medier. Et forseglet bundt til en air-gapped kunde verificeres mod Deres offentlige nøgle, før noget pakkes ud, og kapitel 2.25, Bygning til hver udgave, viser kommandoen.

Leveringsidentitet

Et plugin leveres gennem flere ting, der hver har et navn: dets repositories, en signeringsnøgle, et udrulnings-namespace, et registry-præfiks, et databaseskema, et sæt domæner og en ændringspolitik. Hver af dem er et sted, hvor to plugins kan kollidere, eller hvor ét plugin kan glide ud af kurs. Leveringsidentiteten er én signeret post pr. plugin, der rummer dem alle, så hver kontrol på udgivelsesvejen læser det samme svar og afviser ved uoverensstemmelse.

De bidrager med Deres del gennem manifestet og intet andet: schema, db, domains, changePolicy og repository-URL'en. Platformen fuldender posten med resten og signerer den. De navngiver aldrig selv Deres namespace, registry-præfiks eller signeringsnøgle. Disse tildeles Dem, og et manifest, der forsøgte at erklære dem, ville fremsætte en påstand, som kontrollerne derefter måtte afvise at tro på.

Den signerede post rummer elleve felter: pluginets slug, den ejende organisation, den organisation, der bygger det, dets repositories, navnet på dets signeringsnøgle, dets udrulnings-namespace, dets registry-præfiks, dets databaseskema, dets domæner, dets ændringspolitik og en kort liste over ældre image-navne, som det brugte, før dets registry-præfiks fandtes. Den sidste liste kan kun blive kortere. Fordi den er signeret, kan en ny signatur fjerne en post, og intet kan stille og roligt tilføje en. Signaturen er Ed25519 over den standardiserede kanoniske JSON-form af de elleve felter, så en post med "Tomás" eller "Sinéad" verificeres ens overalt.

Når en udgivelse ikke stemmer overens med sin post, vinder den første afvisning:

Kode Hvornår HTTP
DELIVERY_IDENTITY_MISSING Der findes ingen post for pluginet 403
DELIVERY_PATH_REFUSED En image-push uden for registry-præfikset, som ikke står på den signerede liste over ældre navne 403
NAMESPACE_MISMATCH En udrulning, der er rettet mod et andet namespace 403
IMAGE_NAME_COLLISION Et image-navn, som et andet plugin allerede gør krav på 409
CHANGE_CLASS_NOT_PERMITTED En ændringsklasse, som politikken ikke styrer 403

IMAGE_NAME_COLLISION er den, der overrasker folk. Vælg et andet navn, og genbrug aldrig et: et delt image-navn betyder, at ét plugins forfremmelse kan flytte et andet plugins pods.

Migreringer, fastlagte og afgrænsede

En migrering leveres inde i Deres plugins image og kører, før den nye version starter, gennem SDK'ets ene migreringskører, nexus-migrate. De skriver ikke Deres egen anvender. Før en udgivelse kan flyttes, anvender den samme kører Deres migreringer én fil ad gangen mod en midlertidig database, så en migrering, der fejler, fejler dér. Skabelonens shadow-build kalder køreren én gang pr. fil i rækkefølge og registrerer hver fil, som produktionen vil gøre det.

Kørerens regler er dem, kontrolpunkterne tjekker, skrevet som kode:

  1. Den forbinder som Deres skemas migratorrolle og kører hver fil som skemaets ejer. Ethvert andet login, først og fremmest en superbruger, afvises. En fil, der selv forsøger at skifte rolle, afvises, før noget køres.
  2. Tenancy-filen, nummer 0, redigeres aldrig, efter den er anvendt. En ændring af tenancy får sin egen revisionsfil, 000_tenancy_r<N>.sql, som nexus-tenancy render --revision <N> skriver for Dem.
  3. Normalt ejer køreren hver fils transaktion og afviser en BEGIN eller COMMIT inde i den. En fil, der selv styrer sine transaktioner, erklærer, at den kører pr. sætning, og så skal hver BEGIN, den åbner, have et modstykke.
  4. Den fører en logbog med én række pr. fil, med filens SHA-256 og hvordan den kørte. En anvendt fil ændres aldrig på stedet; en ændring er en ny nummereret 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

Afgrænset betyder, at hver ny tabel har organization_id, owner_user_id og business_unit_id, plus markørkolonnen is_demo, medmindre gates/demo-exempt.json undtager tabellen med en begrundelse, med en primærnøgle, der starter med organisationen, og fremmednøgler, der bærer den, og med tvungen sikkerhed på rækkeniveau. Kontrolpunktet migrations-are-scoped tjekker disse regler i hver fil, og migrations-commit-what-they-open tæller, at hver fil committer det, den åbner. Det andet kontrolpunkt findes, fordi en migrering, der stille rullede tilbage, engang afsluttede med 0, og den tabel, den skulle have oprettet, fandtes aldrig.

Endnu en fil hører til hver udgivelse. scripts/ci/required-env udskriver de miljøvariabler, Deres tjeneste skal bruge for at starte, som et JSON-array hentet fra Deres konfigurationsindlæser. Udgivelsesvejen kører den og afviser en udgivelse, hvis udrulning ikke angiver dem alle, så en manglende variabel fanges før udgivelsen og ikke af en pod, der ikke vil starte.

node scripts/ci/required-env

Udgivelse af færdigheder

De to slags færdigheder når ud til folk ad forskellige veje, så udgiv dem forskelligt.

En manifestfærdighed, en typet række i Deres plugins skills[], leveres med pluginet og gennemgår den samme forfremmelse som resten af det. Onboarding synkroniserer hele færdighedssættet til registret ved hver udgivelse. Udelad en færdighed fra sættet, og den deaktiveres, og på Enterprise tager en synkronisering med én fejlbehæftet færdighed ingen af dem med, så den forrige version fortsætter med at køre i stedet for halvdelen af den nye.

En Skills Engine-skill udgives fra biblioteket. På Enterprise venter en skill, der tilføjer et skriveværktøj, på, at to navngivne personer godkender den med deres passkeys, og forslagsstilleren kan ikke være en af dem. En godkendt version kører derefter i shadow, så i canary for én enhed bag navngivne gates og derefter for alle, og den stopper sig selv, hvis en gate ikke er opfyldt. Hvis Deres plugin og en Skills Engine-skill afhænger af hinanden, skal De udgive skillen først og lade den nå alle, før den plugin-udgivelse, der kalder den, forlader pilotfasen.

Kanaler og installationer

Når en udgivelse har bestået pilotfasen og nået alle enheder, tilbydes den på en kanal, og hver enhed vælger sin kanal. Enhedens administrator godkender hvert skift. Siden Channels and installs viser, hvilke enheder der kører hvilken version, med fejlrater udelukkende som antal: De ser, hvordan Deres udvidelse opfører sig, aldrig hvad nogen har gjort med den.

Kanaler og installationer
Kanaler og installationer
Hvilke enheder der kører hvilken version af carrier-sync, med en tilbagerulning åben for én enhed. Læg mærke til, hvad dialogboksen siger ændres, hvad der forbliver, og at den kræver en anden person, enhedens egen administrator.

Vores carrier-sync-plugin kører tre versioner på én gang, og det er normalt. De fleste enheder er på den aktuelle udgivelse, én enhed bliver på en ældre version på en kanal, der opretholdes til en angivet dato, og en release candidate ligger på en kanal, som ingen endnu har valgt. Kæmp ikke imod det; en enhed, der har brug for stabilitet til en revision, har ret til det.

Logfiler og målinger for jeres udvidelse

Siden med logfiler og målinger for Deres pakke er låst til Deres egne workloads i de enheder, hvor De må se. De kan filtrere efter enhed og miljø, og De ser antal, tidsforbrug og tilstande.

Deres pakkes logfiler og målinger
Deres pakkes logfiler og målinger
Cold chains egne logfiler og målinger, filtreret til Rotterdam-piloten. Se på loglinjerne: den person, der rapporterede en afvigelse, er skjult, og teksten i reklamationsnoten logges aldrig.

Personlige felter erstattes, før en linje skrives, og kundeindhold såsom reklamationstekst, mail eller dokumentindhold skrives aldrig til logfiler. Logfiler opbevares i 14 dage. Organisationen fastsættes af gatewayen, aldrig af Deres forespørgsel, så en forespørgsel, der nævner en anden organisation, afvises med TENANT_BOUNDARY. Assistenten i docken kan læse de samme logfiler sammen med Dem, og kun disse: da jeg spurgte den, hvorfor afvigelsesregistreringer kom for sent ind en morgen, sporede den 18 minutters genforsøg til dublerede målinger fra én kajs strømforsyning.

Tilbagerulning

Der findes to slags tilbagerulning, og begge er gennemgåede ændringer frem for kontakter.

Tilbagerulning af et miljø bruger den foregående version. Hvert miljø beholder den i 30 dage. Tilbagerulningen forberedes som en ændring af udgivelsen, viser på forhånd, hvad den vil gøre, og kræver en anden person; når den er godkendt, ruller pipelinen tilbage på cirka et minut. Hver tilbagerulning tages der tid på, og det samme gælder hver øvelse, så øv Dem på en, før De får brug for det. Tilbagerulning af én enhed sker via siden Channels and installs. Dialogboksen for tilbagerulning angiver, hvad der ændres (enheden kører den ældre version igen, og dens fejlrate overvåges i en time), hvad der forbliver (de øvrige enheder samt enhedens indstillinger og poster), begrundelsen, og hvem den anden person er: enhedens administrator.

Indstillinger og poster bevares ved en tilbagerulning, så planlæg hver udgivelse ud fra den antagelse, at versionen før den kan komme til at køre igen på de data, som den nyere version skrev. Det er den praktiske grund til at holde migreringer additive inden for en udgivelse, De måske ruller tilbage, og grunden til, at vi beder to personer om at godkende hver enkelt. En modelændring er det samme: en reviewer kan, og bør, bede om tilbagerulningsplanen for en anmodning om grafændring, før den godkendes.

Skills rulles mere skånsomt tilbage. At flytte live-mærket tilbage til en tidligere version er ét trin, og kørsler, der allerede er i gang, afsluttes på den version, de startede med.

Udfasning af en version

En udgivelse redigeres aldrig, når den først er lavet. En version, der ikke længere bør bruges, trækkes tilbage, og en rettelse leveres som et nyt versionsnummer. SDK'ets egne udgivelseskanaler følger samme vane: en dårlig SDK-version trækkes tilbage og erstattes aldrig med andet indhold under samme nummer. Gør det samme, for et versionsnummer, der kan betyde to forskellige builds, gør al dokumentation om det værdiløs.

Tilbagetrækning af et plugin eller en pakke stopper nye installationer. Enhederne beholder den version, de kører, indtil de skifter, så en tilbagetrækning er et signal og en frist, ikke en slukknap. Fortæl enhedsadministratorerne, hvilken version de skal skifte til, og hvornår.

Udfasning af en skill følger samme idé med ét trin mere. Skills Engine flytter alle tilbageværende kaldere til en erstatning efter at have kørt erstatningens cases, stopper nye kørsler og bevarer versionerne, cases og de forseglede kørselsposter, så skillen kan genindføres, hvis erstatningen viser sig at være forkert.

En tjekliste til udgivelse

Dette er den liste, vi gennemgår før hver Cold chain-udgivelse. Den er kort, fordi platformen kontrollerer det meste af den for os.

  1. Versionerne stemmer overens: manifestet, pack.json og vidensmodellen, hvis den er ændret.
  2. Alle gates er grønne lokalt fra en ren tilstand, og hver ny test er vist at fejle først.
  3. Siden Manifest and permissions viser ingen udvidelse, eller udvidelsen er tilsigtet, og reviewerne ved hvorfor.
  4. Hver migrering er en ny nummereret fil, afgrænset og anvendt uden fejl på en midlertidig database.
  5. scripts/ci/required-env angiver alle variabler, tjenesten har brug for, og deploymentet sætter hver enkelt.
  6. Tilbagerulningsplanen er beskrevet i ændringen, også for enhver modelændring.
  7. To reviewere, der ikke er forfatteren, er tilgængelige i denne uge.

Det sidste punkt lyder trivielt. Det er det, der har forsinket flere af vores udgivelser end alle gates tilsammen.