Logga inBoka en genomgång

Kapitel 2.28

Släppa ditt tillägg

Hur ett insticksprogram eller paket går från ett godkänt bygge till de enheter som kör det, och hur det tas bort igen. Versioner, utgivningsgranskning, kanaler och installationer, signering, ändringsgodkännanden, posten för leveransidentitet, migreringar, återställning och avveckling av en version.

Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

18 minuters läsning

Cold chain 0.4.0 var den första av våra versioner som begärde mer än den föregående. Den lade till sändning av e-post och en extern adress, för larm om kylcontainrar. Bygget var grönt, testerna gick igenom på alla tre syntetiska filialer, och ändå låg den kvar i utvecklingsutrymmet i två dagar medan två personer läste vad den begärde och en tredje godkände adressen. Så är det tänkt att det ska kännas att släppa en version på Nexus: koden är den enkla delen, och underlaget och godkännandena är själva releasen.

Detta kapitel behandlar allt mellan ett grönt bygge och en version som körs för alla enheter, samt vägarna tillbaka. Själva befordringsvägen, från utvecklingsutrymme till staging till en pilotenhet till alla enheter, presenteras i kapitel 2.24, Bygga en anpassad vertikal från början till slut, och jag upprepar inte dess grindar här. En regel ramar in allt. Driftsättning sker endast via installationens releasekanaler. Det finns ingen bakdörr för en brådskande rättning, och ingen redigerar en körande avbild för hand.

Versioner

Tre versionsnummer ändras i en paketrelease, och det lönar sig att hålla isär dem i huvudet.

Vad Var den finns Exempel Regel
Pluginet version i nexus.manifest.json 0.4.0 Semantisk version; ett förhandsversionssuffix som -rc.1 är tillåtet
Paketet version i pack.json 0.4.0 Ändras med paketets linser, ord och kluster
Kunskapsmodellen Modellens egen version 1.3 till 1.4 Ändras endast genom en ändringsbegäran för grafen

Ett utvecklingsbygge har ett suffix, 0.4.0-dev, tills det når staging. Håll plugin- och paketversionerna lika när de levereras tillsammans; det sparar en diskussion i varje releasegranskning om vilket nummer underlaget hör till.

Två andra versioner är låsta snarare än valda. Paketets mallversion (domain-pack@1.6.0 för Cold chain) fastställs när paketet skapas och ändras endast som en granskad ändring. SDK:n (software development kit) installeras i en exakt version, aldrig ett intervall, så att samma bygge ger samma resultat nästa månad:

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

Skills Engine-färdigheter har också versioner, och de beter sig annorlunda. Varje publicerad version är fast, och live, canary och shadow är etiketter på versioner. Att växla tillbaka flyttar en etikett, och körningar som redan pågår slutförs på den version de startade med.

Innan du begär granskning: manifestet

Sidan Manifest och behörigheter jämför vad denna release deklarerar med den senaste releasen: dess omfång, dess lagringar, dess utgående adresser och dess sandlådeprofil. Läs den innan ni ber någon att granska, eftersom den visar exakt vad granskarna kommer att ombes godta.

Manifest och behörigheter
Manifest och behörigheter
Vad Cold chain 0.4.0 deklarerar jämfört med 0.3.2. Lägg märke till de två raderna som är markerade som utvidgningar, sändning av e-post och en extern adress, och skylten som anger att releasen inte går vidare från utvecklingsutrymmet förrän två granskare godtar dem.

En release som begär mer än dess manifest tidigare deklarerade hålls kvar där den är, med MANIFEST_SCOPE_WIDENED, tills två granskare godtar det utvidgade manifestet. En extern adress kräver dessutom godkännande av den som ansvarar för externa adresser hos kunden; det godkännandet ges för en fast period, och vårt gällde i 12 månader. Ni har två vägar framåt: ta bort raderna eller begära granskning. Sidan erbjuder båda knapparna.

Varje rad på den sidan upprätthålls vid körning, inte bara vid granskning. Varje verktygsanrop kontrolleras mot de deklarerade omfången, en extern adress blockeras om den inte finns listad, och sandlådeprofilen tillåter inget annat nätverk. Ett plugin som försöker nå något det inte har deklarerat nekas, och den enda lösningen är en ny release som deklarerar det.

Utgivningsgranskning

Sidan Releasegranskning samlar underlaget för en release i en tabell, för en granskare som inte är författaren.

Releasegranskning
Utgivningsgranskning
En andra granskares vy av Cold chain 0.4.0, med underlagstabellen, omfångsdiffen och kommentarerna. Lägg märke till skylten till höger: författaren kan inte godkänna sin egen release.
Underlag Vad det visade för 0.4.0
Tester 66 av 66, på tre syntetiska filialer
Kvalitetskontroller Dokumentationen och koden stämmer överens
Policy Varje lins begränsar endast; personuppgiftsfält avstängda som standard
Signaturer Avbild och paket signerade av pipelinen
Omfångsdiff Lägger till sändning av e-post och en extern adress, med dess godkännande
Kompatibilitet Plattformsversionen och den baspaketversion den testades mot
Modelländring Torrkörning av ändringsbegäran för grafen: 1 284 länkar omdöpta, inget borttaget

Under tabellen finns kommentarerna om ändringen och ursprungsuppgifterna: vilken pipeline som byggde den, från vilken ändring, avbildens digest och mallen. Granskare godkänner med sin passkey. Två granskare som inte är författaren godkänner, och pipelinen flyttar sedan releasen till staging. Författaren räknas aldrig som granskare, och ett försök nekas med NEEDS_SECOND_PERSON. En granskningsbegäran förfaller efter 3 dagar.

Besvara granskarnas frågor i kommentarerna, inte i ett chattfönster. Under vår granskning frågade vår regelefterlevnadsansvarige varför skadebelopp klassades som kommersiellt, och den andra granskaren bad om återställningsplanen för modelländringen. Båda svaren ingår nu i releasens historik, och det är där nästa granskare kommer att titta.

Godkännanden för ändringspolicy

Releasegranskningen omfattar releasen som helhet. Blocket changePolicy i manifestet går längre: det anger vilka klasser av ändringar i ert plugins driftsättningsbara delar som kräver godkännande, och från hur många personer.

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

De tre klasserna är website (webbappen), bff (backend för frontend) och migration (en databasmigrering). Varje klass som anges i classes måste ha ett eget antal i approvals, från 1 till 10. En klass som ni utelämnar är ostyrd, och schemat tvingar er att skriva det som ett val i stället för att hamna där genom utelämnande. Vi kräver två godkännanden för migreringar eftersom en migrering är den enda ändring som är svår att ta tillbaka.

Godkännanden räknas i distinkta personer, och den som föreslår ändringen är aldrig en av dem. Reglerna som upprätthåller detta är värda att känna till, eftersom var och en har en nekning:

  • Ett godkännande från den person som föreslog ändringen nekas med TRUST_APPROVAL_SELF_APPROVAL.
  • En person som inte får göra en ändring av den klassen över huvud taget nekas med CHANGE_CLASS_NOT_PERMITTED.
  • När någon commit i ändringen är signerad av organisationens agentidentitet är kvorumet det vanliga minimumet plus ett, och agentens egen röst räknas inte.
  • Varje godkännande registrerar den diff och det huvud det såg. Om ändringen flyttas efter det senaste godkännandet nekas sammanslagningen med HASH_MISMATCH, och godkännandena måste samlas in på nytt för det nya innehållet.

Den tredje regeln spelar roll om ni bygger med ett AI-kodningsverktyg (artificiell intelligens), som kapitel 2.26, Bygga med AI-kodningsverktyg, beskriver. Arbete som en agent har skrivit kräver ett mänskligt godkännande mer än arbete som en person har skrivit. Planera för det.

Signering och verifiering

Varje avbild och paket signeras av den pipeline som byggde det, och en signerad avbild är en av grindarna in till staging. Ett utvecklingsutrymme kör endast signerade avbilder från början. På Enterprise ställer en administratör in varje namnrymd antingen på att registrera osignerade avbilder eller på att neka dem, och flyttar namnrymder till nekande en i taget, så att produktionen till slut endast kör avbilder som pipelinen har byggt och signerat. Signering är en del av bygget, inte något ni lägger till före en release.

Regeln som löper genom allt detta är att en signatur som misslyckas är en nekning, aldrig en varning. En kontroll som får SIG_INVALID stoppar. Den faller inte tillbaka på den osignerade versionen och den fortsätter inte med en anteckning i en logg, eftersom en varning i en bygglogg är ett godkänt för alla som inte läste den.

Samma regel gäller allt ni lämnar över på media. Ett förseglat paket för en air-gapped kund verifieras mot er publika nyckel innan något packas upp, och kapitel 2.25, Bygga för varje utgåva, visar kommandot.

Leveransidentitet

Ett plugin levereras genom flera saker som var och en har ett namn: dess arkiv, en signeringsnyckel, en driftsättningsnamnrymd, ett registerprefix, ett databasschema, en uppsättning domäner och en ändringspolicy. Var och en av dem är en plats där två plugins kan krocka, eller där ett plugin kan glida iväg. Leveransidentiteten är en signerad post per plugin som innehåller dem alla, så att varje kontroll längs releasevägen läser samma svar och nekar vid en avvikelse.

Ni bidrar med er del genom manifestet och inget annat: schema, db, domains, changePolicy och arkivets URL. Plattformen kompletterar posten med resten och signerar den. Ni namnger aldrig er egen namnrymd, ert registerprefix eller er signeringsnyckel. Dessa tilldelas er, och ett manifest som försökte deklarera dem skulle göra ett påstående som kontrollerna sedan måste misstro.

Den signerade posten innehåller elva fält: pluginets slug, den ägande organisationen, organisationen som bygger det, dess arkiv, namnet på dess signeringsnyckel, dess driftsättningsnamnrymd, dess registerprefix, dess databasschema, dess domäner, dess ändringspolicy samt en kort lista över äldre avbildsnamn som det använde innan dess registerprefix fanns. Den sista listan kan bara krympa. Eftersom den är signerad kan en ny signatur ta bort en post, och inget kan lägga till en i tysthet. Signaturen är Ed25519 över den kanoniska standardformen av JSON för de elva fälten, så att en post med "Tomás" eller "Sinéad" i sig verifieras likadant överallt.

När en release inte stämmer med sin post gäller den första nekningen:

Kod När HTTP
DELIVERY_IDENTITY_MISSING Det finns ingen post för pluginet 403
DELIVERY_PATH_REFUSED En push av en avbild utanför registerprefixet som inte finns på den signerade listan över äldre namn 403
NAMESPACE_MISMATCH En driftsättning som riktar sig mot en annan namnrymd 403
IMAGE_NAME_COLLISION Ett avbildsnamn som ett annat plugin redan gör anspråk på 409
CHANGE_CLASS_NOT_PERMITTED En ändringsklass som policyn inte styr 403

IMAGE_NAME_COLLISION är den som överraskar folk. Välj ett annat namn och återanvänd aldrig ett: ett delat avbildsnamn innebär att ett plugins befordran kan flytta ett annat plugins poddar.

Migreringar, verkställda och avgränsade

En migrering levereras i ert plugins avbild och körs innan den nya versionen startar, via SDK:ns enda migreringskörare, nexus-migrate. Ni skriver inte er egen applikator. Innan någon release kan flyttas tillämpar samma körare era migreringar en fil i taget mot en tillfällig databas, så att en migrering som misslyckas misslyckas där. Mallens skuggbygge anropar köraren en gång per fil, i ordning, och registrerar varje fil så som produktionen kommer att göra.

Körarens regler är de som grindarna kontrollerar, skrivna som kod:

  1. Den ansluter som ert schemas migratorroll och kör varje fil som schemats ägare. All annan inloggning, i första hand en superanvändare, nekas. En fil som själv försöker byta roll nekas innan något körs.
  2. Tenancy-filen, numrerad 0, redigeras aldrig efter att den har tillämpats. En ändring av tenancy får en egen revisionsfil, 000_tenancy_r<N>.sql, som nexus-tenancy render --revision <N> skriver åt er.
  3. Normalt äger köraren varje fils transaktion och nekar en BEGIN eller COMMIT i den. En fil som hanterar sina egna transaktioner deklarerar att den körs per sats, och då måste varje BEGIN den öppnar ha en motsvarighet.
  4. Den för en liggare, en rad per fil, med filens SHA-256 och hur den kördes. En tillämpad fil ändras aldrig på plats; en ändring är en ny numrerad 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

Avgränsad innebär att varje ny tabell har organization_id, owner_user_id och business_unit_id, plus markörkolumnen is_demo om inte gates/demo-exempt.json undantar tabellen med en motivering, med en primärnyckel som börjar med organisationen och främmande nycklar som bär den, och med radnivåsäkerhet påtvingad. Grinden migrations-are-scoped kontrollerar dessa regler i varje fil, och migrations-commit-what-they-open räknar efter att varje fil bekräftar det den öppnar. Den andra grinden finns eftersom en migrering som i tysthet rullades tillbaka en gång avslutades med 0, och tabellen den skulle ha skapat fanns aldrig.

Ytterligare en fil hör till varje release. scripts/ci/required-env skriver ut de miljövariabler som er tjänst behöver för att starta, som en JSON-array hämtad från er konfigurationsladdare. Releasevägen kör den och nekar en release vars driftsättning inte sätter var och en av dem, så att en saknad variabel upptäcks före releasen, inte av en podd som inte startar.

node scripts/ci/required-env

Släppa färdigheter

De två typerna av färdigheter når människor via olika vägar, så släpp dem på olika sätt.

En manifestfärdighet, en typad rad i ert plugins skills[], levereras med pluginet och går igenom samma befordran som resten av det. Onboarding synkroniserar hela färdighetsuppsättningen till registret vid varje release. Utelämna en färdighet ur uppsättningen så inaktiveras den, och på Enterprise tar en synkronisering med en felaktig färdighet ingen av dem, så att den föregående versionen fortsätter att köras i stället för hälften av den nya.

En Skills Engine-färdighet publiceras från biblioteket. På Enterprise väntar en färdighet som lägger till ett skrivverktyg på att två namngivna personer godkänner den med sina passnycklar, och den som föreslår den kan inte vara en av dem. En godkänd version körs sedan i skuggläge, därefter som canary för en enhet bakom namngivna grindar, därefter för alla, och den stoppar sig själv om en grind inte uppfylls. Om ert plugin och en Skills Engine-färdighet är beroende av varandra, publicera då färdigheten först och låt den nå alla innan den plugin-version som anropar den lämnar piloten.

Kanaler och installationer

När en version har passerat piloten och nått alla enheter erbjuds den på en kanal, och varje enhet väljer sin kanal. Enhetens administratör godkänner varje byte. Sidan Kanaler och installationer visar vilka enheter som kör vilken version, med felfrekvenser endast som antal: ni ser hur ert tillägg beter sig, aldrig vad någon har gjort med det.

Kanaler och installationer
Kanaler och installationer
Vilka enheter som kör vilken version av carrier-sync, med en återställning öppen för en enhet. Lägg märke till vad dialogrutan säger ändras, vad som består, och att den kräver en andra person, enhetens egen administratör.

Vårt plugin carrier-sync kör tre versioner samtidigt, och det är normalt. De flesta enheter har den aktuella versionen, en enhet stannar kvar på en äldre version på en kanal som behålls till ett angivet datum, och en releasekandidat finns på en kanal som ingen har valt ännu. Motarbeta det inte; en enhet som behöver stabilitet inför en revision har rätt till det.

Ditt tilläggs loggar och mätvärden

Sidan för loggar och mätvärden för ert paket är låst till era egna arbetslaster, i de enheter där ni får titta. Ni kan filtrera på enhet och miljö, och ni ser antal, tider och tillstånd.

Ert pakets loggar och mätvärden
Ert pakets loggar och mätvärden
Cold chains egna loggar och mätvärden, filtrerade till piloten i Rotterdam. Titta på loggraderna: personen som rapporterade en avvikelse är dold, och texten i skadeanmälans anteckning loggas aldrig alls.

Personuppgiftsfält ersätts innan en rad skrivs, och kundinnehåll som skadeanmälningstext, e-post eller dokumentinnehåll skrivs aldrig till loggar. Loggar sparas i 14 dagar. Organisationen sätts av gatewayen, aldrig av er fråga, så en fråga som anger en annan organisation avvisas med TENANT_BOUNDARY. Assistenten i dockan kan läsa samma loggar tillsammans med er, och endast dessa: när jag frågade den varför avvikelseposter kom in sent en morgon spårade den 18 minuter av omförsök till dubblerade avläsningar från en kajs strömmatning.

Återställa

Det finns två sorters återställning, och båda är granskade ändringar snarare än brytare.

Återställning av en miljö använder den föregående versionen. Varje miljö behåller den i 30 dagar. Återställningen förbereds som en ändring av versionen, förhandsvisar vad den kommer att göra och kräver en andra person; när den är godkänd återställer pipelinen på ungefär en minut. Varje återställning tidsmäts, och det gör även varje övning, så öva en innan ni behöver den. Återställning av en enhet görs på sidan Kanaler och installationer. Dialogrutan för återställning anger vad som ändras (den enheten kör den äldre versionen igen, och dess felfrekvens övervakas i en timme), vad som består (de andra enheterna, samt enhetens inställningar och poster), orsaken, och vem den andra personen är: den enhetens administratör.

Inställningar och poster behålls vid en återställning, så planera varje version utifrån antagandet att versionen före den kan köras igen på de data som den nyare skrev. Det är det praktiska skälet till att hålla migreringar additiva inom en version som ni kan komma att återställa, och skälet till att vi ber två personer godkänna var och en. En modelländring är likadan: en granskare kan, och bör, begära återställningsplanen för en ändringsbegäran för grafen innan den godkänns.

Färdigheter återställs mjukare. Att flytta live-etiketten tillbaka till en tidigare version är ett steg, och körningar som redan pågår slutförs på den version de startade med.

Avveckla en version

En version redigeras aldrig när den väl har släppts. En version som inte längre bör användas dras tillbaka, och en korrigering levereras som ett nytt versionsnummer. SDK:ns egna releasekanaler följer samma vana: en felaktig SDK-version dras tillbaka, ersätts aldrig med annat innehåll under samma nummer. Gör likadant, eftersom ett versionsnummer som kan betyda två olika byggen gör varje belägg om det värdelöst.

Att dra tillbaka ett plugin eller paket stoppar nya installationer. Enheter behåller den version de kör tills de byter, så att dra tillbaka är en signal och en tidsfrist, inte en avstängningsknapp. Meddela enhetsadministratörerna vilken version de ska byta till och när.

Att avveckla en färdighet följer samma idé med ytterligare ett steg. Skills Engine flyttar alla återstående anropare till en ersättare efter att ha kört ersättarens testfall, stoppar nya körningar och behåller versionerna, testfallen och de förseglade körningsposterna, så att färdigheten kan återinföras om ersättaren visar sig vara fel.

En checklista för utgivning

Det här är listan vi läser före varje Cold chain-version. Den är kort eftersom plattformen kontrollerar det mesta åt oss.

  1. Versionerna stämmer överens: manifestet, pack.json, och kunskapsmodellen om den ändrats.
  2. Varje grind är grön lokalt, från rent läge, och varje nytt test har visats misslyckas först.
  3. Sidan Manifest och behörigheter visar ingen utvidgning, eller så är utvidgningen avsiktlig och granskarna vet varför.
  4. Varje migrering är en ny numrerad fil, avgränsad och tillämpad utan fel mot en engångsdatabas.
  5. scripts/ci/required-env listar varje variabel som tjänsten behöver, och driftsättningen sätter var och en.
  6. Återställningsplanen är beskriven i ändringen, även för eventuella modelländringar.
  7. Två granskare som inte är författaren är tillgängliga den här veckan.

Den sista punkten låter trivial. Det är den som har försenat fler av våra versioner än alla grindar tillsammans.