InloggenBriefing plannen

Hoofdstuk 2.28

Uw extensie vrijgeven

Hoe een plug-in of pakket van een geslaagde build naar de eenheden gaat die deze draaien, en hoe deze weer wordt verwijderd. Versies, releasebeoordeling, kanalen en installaties, ondertekening, wijzigingsgoedkeuringen, het identiteitsrecord van de levering, migraties, terugdraaien en het uitfaseren van een versie.

Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

18 minuten leestijd

Cold chain 0.4.0 was onze eerste release die meer vroeg dan de vorige. Er kwamen het verzenden van e-mail en één extern adres bij, voor waarschuwingen over koelcontainers. De build was groen, de tests slaagden op alle drie de synthetische vestigingen, en toch bleef de release twee dagen in de ontwikkelruimte staan, terwijl twee mensen lazen wat ze vroeg en een derde het adres goedkeurde. Zo hoort releasen op Nexus te voelen: de code is het makkelijke deel, en het bewijs en de goedkeuringen vormen de release.

Dit hoofdstuk behandelt alles tussen een groene build en een versie die voor elke eenheid draait, en de manieren om weer terug te gaan. Het promotiepad zelf, van ontwikkelruimte naar staging naar een piloteenheid naar alle eenheden, wordt geïntroduceerd in hoofdstuk 2.24, Een eigen verticale oplossing van begin tot eind bouwen, en ik herhaal de poorten daarvan hier niet. Eén regel vormt het kader voor alles. Uitrollen gebeurt uitsluitend via de releasekanalen van de installatie. Er is geen zijdeur voor een dringende fix, en niemand bewerkt een draaiende image met de hand.

Versies

In een pack-release veranderen drie versienummers, en het loont om die in uw hoofd uit elkaar te houden.

Wat Waar het staat Voorbeeld Regel
De plugin version in nexus.manifest.json 0.4.0 Semantische versie; een pre-release-achtervoegsel zoals -rc.1 is toegestaan
Het pack version in pack.json 0.4.0 Verandert mee met de lenzen, woorden en clusters van het pack
Het kennismodel De eigen versie van het model 1.3 naar 1.4 Verandert alleen via een wijzigingsverzoek voor de graaf

Een ontwikkelbuild draagt een achtervoegsel, 0.4.0-dev, totdat deze staging bereikt. Houd de versies van de plugin en het pack gelijk wanneer ze samen worden uitgebracht; dat bespaart in elke releasebeoordeling een discussie over bij welk nummer het bewijs hoort.

Twee andere versies worden vastgezet in plaats van gekozen. De templateversie van het pack (domain-pack@1.6.0 voor Cold chain) wordt vastgelegd wanneer het pack wordt gemaakt en verandert alleen als beoordeelde wijziging. De SDK (software development kit) wordt op een exacte versie geïnstalleerd, nooit op een bereik, zodat dezelfde build volgende maand hetzelfde resultaat geeft:

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

Skills van de Skills Engine hebben ook versies, en die gedragen zich anders. Elke gepubliceerde versie ligt vast, en live, canary en shadow zijn labels op versies. Terugschakelen verplaatst een label, en runs die al bezig zijn, worden afgerond op de versie waarmee ze zijn gestart.

Voordat u een beoordeling aanvraagt: het manifest

De pagina Manifest en machtigingen vergelijkt wat deze release declareert met de vorige release: de scopes, de opslag, de uitgaande adressen en het sandboxprofiel. Lees deze pagina voordat u iemand om een beoordeling vraagt, want ze vertelt u precies wat de beoordelaars zal worden gevraagd te accepteren.

Manifest en machtigingen
Manifest en machtigingen
Wat Cold chain 0.4.0 declareert ten opzichte van 0.3.2. Let op de twee regels die als verruiming zijn gemarkeerd, het verzenden van e-mail en één extern adres, en op het label dat aangeeft dat de release niet verder gaat dan de ontwikkelruimte totdat twee beoordelaars ze accepteren.

Een release die meer vraagt dan het manifest eerder declareerde, wordt tegengehouden waar ze is, met MANIFEST_SCOPE_WIDENED, totdat twee beoordelaars het ruimere manifest accepteren. Een extern adres vereist bovendien de goedkeuring van degene die bij de klant eigenaar is van externe adressen; die goedkeuring wordt voor een vaste termijn gegeven, en de onze gold voor 12 maanden. U hebt twee mogelijkheden: de regels verwijderen of om een beoordeling vragen. De pagina biedt beide knoppen.

Elke regel op die pagina wordt tijdens de uitvoering afgedwongen, niet alleen beoordeeld. Elke toolaanroep wordt gecontroleerd tegen de gedeclareerde scopes, een extern adres wordt geblokkeerd tenzij het is opgenomen, en het sandboxprofiel staat geen ander netwerk toe. Een plugin die iets probeert te bereiken wat hij niet heeft gedeclareerd, wordt geweigerd, en de enige oplossing is een nieuwe release die het declareert.

Releasebeoordeling

De pagina Releasebeoordeling zet het bewijs voor één release in één tabel, voor een beoordelaar die niet de auteur is.

Releasebeoordeling
Releasebeoordeling
De weergave van een tweede beoordelaar van Cold chain 0.4.0, met de bewijstabel, het scopeverschil en de opmerkingen. Let op het label rechts: de auteur kan zijn eigen release niet goedkeuren.
Bewijs Wat het liet zien voor 0.4.0
Tests 66 van 66, op drie synthetische vestigingen
Kwaliteitscontroles De documentatie en de code komen overeen
Beleid Elke lens beperkt alleen; persoonlijke velden standaard uit
Handtekeningen Image en pakket ondertekend door de pipeline
Scopeverschil Voegt het verzenden van e-mail en één extern adres toe, met de bijbehorende goedkeuring
Compatibiliteit De platformversie en de versie van het basispack waartegen is getest
Modelwijziging De proefrun van het wijzigingsverzoek voor de graaf: 1.284 koppelingen hernoemd, niets verwijderd

Onder de tabel staan de opmerkingen bij de wijziging en de herkomst: welke pipeline het heeft gebouwd, vanuit welke wijziging, de image-digest en de template. Beoordelaars keuren goed met hun passkey. Twee beoordelaars die niet de auteur zijn, keuren goed, en de pipeline verplaatst de release vervolgens naar staging. De auteur telt nooit als beoordelaar, en een poging daartoe wordt geweigerd met NEEDS_SECOND_PERSON. Een beoordelingsverzoek vervalt na 3 dagen.

Beantwoord de vragen van de beoordelaars in de opmerkingen, niet in een chatvenster. Tijdens onze beoordeling vroeg onze compliance officer waarom het claimbedrag als commercieel was geclassificeerd, en de tweede beoordelaar vroeg om het terugdraaiplan voor de modelwijziging. Beide antwoorden maken nu deel uit van het dossier van de release, en daar zal de volgende beoordelaar kijken.

Goedkeuringen voor wijzigingsbeleid

De releasebeoordeling betreft de release als geheel. Het blok changePolicy in het manifest gaat verder: het geeft aan welke klassen wijzigingen aan de deployables van uw plugin goedkeuring vereisen, en van hoeveel mensen.

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

De drie klassen zijn website (de webapp), bff (de backend for frontend) en migration (een databasemigratie). Elke klasse die in classes wordt genoemd, moet een eigen aantal hebben in approvals, van 1 tot 10. Een klasse die u weglaat, is onbeheerd, en het schema dwingt u dat als keuze op te schrijven in plaats van er door weglating op uit te komen. Wij vragen twee goedkeuringen voor migraties, omdat een migratie de enige wijziging is die moeilijk terug te draaien is.

Goedkeuringen worden geteld in afzonderlijke personen, en de indiener is daar nooit een van. De regels die dat ondersteunen zijn het kennen waard, omdat elk ervan een weigering heeft:

  • Een goedkeuring van de persoon die de wijziging heeft voorgesteld, wordt geweigerd met TRUST_APPROVAL_SELF_APPROVAL.
  • Iemand die helemaal geen wijziging van die klasse mag aanbrengen, wordt geweigerd met CHANGE_CLASS_NOT_PERMITTED.
  • Wanneer een commit in de wijziging is ondertekend door de agentidentiteit van de organisatie, is het quorum het gebruikelijke minimum plus één, en telt de stem van de agent zelf niet mee.
  • Elke goedkeuring legt de diff en de head vast die zij heeft gezien. Als de wijziging na de laatste goedkeuring verandert, wordt het samenvoegen geweigerd met HASH_MISMATCH, en moeten de goedkeuringen opnieuw worden verzameld voor de nieuwe inhoud.

Die derde regel is van belang als u bouwt met een AI-codeertool (kunstmatige intelligentie), zoals hoofdstuk 2.26, Bouwen met AI-codeertools, beschrijft. Werk dat een agent heeft geschreven, heeft één menselijke goedkeuring meer nodig dan werk dat een persoon heeft geschreven. Houd daar rekening mee.

Ondertekening en verificatie

Elke image en elk pakket wordt ondertekend door de pipeline die het heeft gebouwd, en een ondertekende image is een van de poorten naar staging. Een ontwikkelruimte draait vanaf het begin alleen ondertekende images. Op Enterprise stelt een beheerder elke namespace in op het registreren of het weigeren van niet-ondertekende images, en zet namespaces één voor één om naar weigeren, zodat productie uiteindelijk alleen images draait die de pipeline heeft gebouwd en ondertekend. Ondertekenen is onderdeel van de build, niet iets wat u vóór een release toevoegt.

De regel die door alles heen loopt, is dat een handtekening die faalt een weigering is, nooit een waarschuwing. Een controle die SIG_INVALID ontvangt, stopt. Ze valt niet terug op de niet-ondertekende versie en gaat niet door met een notitie in een log, want een waarschuwing in een buildlog is een goedkeuring voor iedereen die het niet heeft gelezen.

Dezelfde regel geldt voor alles wat u op media overhandigt. Een verzegelde bundel voor een air-gapped klant wordt tegen uw publieke sleutel geverifieerd voordat er iets wordt uitgepakt, en hoofdstuk 2.25, Bouwen voor elke editie, toont de opdracht.

Leveringsidentiteit

Een plugin wordt geleverd via verschillende zaken die elk een naam hebben: de repository's, een ondertekeningssleutel, een deploy-namespace, een registryprefix, een databaseschema, een set domeinen en een wijzigingsbeleid. Elk daarvan is een plek waar twee plugins kunnen botsen of één plugin kan afdrijven. De leveringsidentiteit is één ondertekend record per plugin dat ze allemaal bevat, zodat elke controle op het releasepad hetzelfde antwoord leest en bij een afwijking weigert.

U levert uw deel aan via het manifest en via niets anders: schema, db, domains, changePolicy en de repository-URL. Het platform vult het record aan met de rest en ondertekent het. U benoemt nooit zelf uw namespace, registryprefix of ondertekeningssleutel. Die worden aan u toegewezen, en een manifest dat ze probeerde te declareren, zou een bewering doen die de controles dan zouden moeten wantrouwen.

Het ondertekende record bevat elf velden: de slug van de plugin, de eigenaarsorganisatie, de organisatie die de plugin bouwt, de repository's, de naam van de ondertekeningssleutel, de deploy-namespace, de registryprefix, het databaseschema, de domeinen, het wijzigingsbeleid, en een korte lijst met oudere imagenamen die werden gebruikt voordat de registryprefix bestond. Die laatste lijst kan alleen korter worden. Omdat ze is ondertekend, kan een nieuwe handtekening een vermelding verwijderen en kan niets er ongemerkt een toevoegen. De handtekening is Ed25519 over de standaard canonieke JSON-vorm van die elf velden, zodat een record met "Tomás" of "Sinéad" erin overal op dezelfde manier wordt geverifieerd.

Wanneer een release niet overeenkomt met het record, geldt de eerste weigering:

Code Wanneer HTTP
DELIVERY_IDENTITY_MISSING Er is geen record voor de plugin 403
DELIVERY_PATH_REFUSED Een image-push buiten de registryprefix die niet op de ondertekende lijst met oudere namen staat 403
NAMESPACE_MISMATCH Een deployment die op een andere namespace is gericht 403
IMAGE_NAME_COLLISION Een imagenaam die een andere plugin al claimt 409
CHANGE_CLASS_NOT_PERMITTED Een wijzigingsklasse die het beleid niet beheert 403

IMAGE_NAME_COLLISION is degene die mensen verrast. Kies een andere naam en hergebruik er nooit een: een gedeelde imagenaam betekent dat de promotie van de ene plugin de pods van een andere plugin kan verplaatsen.

Migraties, vastgelegd en afgebakend

Een migratie wordt meegeleverd in de image van uw plugin en draait voordat de nieuwe versie start, via de enige migratierunner van de SDK, nexus-migrate. U schrijft geen eigen applier. Voordat een release verder kan, past dezelfde runner uw migraties één bestand tegelijk toe op een wegwerpdatabase, zodat een migratie die faalt, daar faalt. De shadowbuild van de template roept de runner eenmaal per bestand aan, op volgorde, en registreert elk bestand zoals productie dat zal doen.

De regels van de runner zijn de regels die de poorten controleren, geschreven als code:

  1. Hij maakt verbinding als de migratorrol van uw schema en voert elk bestand uit als eigenaar van het schema. Elke andere login, in de eerste plaats een superuser, wordt geweigerd. Een bestand dat zelf van rol probeert te wisselen, wordt geweigerd voordat er iets draait.
  2. Het tenancybestand, met nummer 0, wordt na toepassing nooit meer bewerkt. Een wijziging in de tenancy krijgt een eigen revisiebestand, 000_tenancy_r<N>.sql, dat nexus-tenancy render --revision <N> voor u schrijft.
  3. Normaal beheert de runner de transactie van elk bestand en weigert hij een BEGIN of COMMIT daarbinnen. Een bestand dat zijn eigen transacties beheert, declareert dat het per statement draait, en dan moet elke BEGIN die het opent, worden afgesloten.
  4. Hij houdt een grootboek bij, één rij per bestand, met de SHA-256 van het bestand en hoe het is uitgevoerd. Een toegepast bestand wordt nooit ter plekke gewijzigd; een wijziging is een nieuw genummerd bestand.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Gescoped betekent dat elke nieuwe tabel organization_id, owner_user_id en business_unit_id bevat, plus de markeringskolom is_demo tenzij gates/demo-exempt.json de tabel met een reden uitzondert, met een primaire sleutel die begint met de organisatie en foreign keys die deze meevoeren, en met afgedwongen row-level security. De poort migrations-are-scoped controleert die regels voor elk bestand, en migrations-commit-what-they-open telt of elk bestand vastlegt wat het opent. De tweede poort bestaat omdat een migratie die ongemerkt was teruggedraaid ooit eindigde met 0, en de tabel die ze had moeten aanmaken nooit heeft bestaan.

Er hoort nog één bestand bij elke release. scripts/ci/required-env drukt de omgevingsvariabelen af die uw service nodig heeft om op te starten, als JSON-array uit uw configuratieloader. Het releasepad voert het uit en weigert een release waarvan de deployment niet elk daarvan instelt, zodat een ontbrekende variabele vóór de release wordt opgemerkt, en niet door een pod die niet start.

node scripts/ci/required-env

Vaardigheden vrijgeven

De twee soorten skills bereiken mensen via verschillende routes, dus brengt u ze verschillend uit.

Een manifestskill, een getypeerde rij in de skills[] van uw plugin, wordt met de plugin meegeleverd en doorloopt dezelfde promotie als de rest ervan. Onboarding synchroniseert bij elke release de volledige set skills naar het register. Laat u een skill weg uit de set, dan wordt deze uitgeschakeld, en op Enterprise neemt een synchronisatie met één foute skill er geen enkele over, zodat de vorige versie blijft draaien in plaats van de helft van de nieuwe.

Een Skills Engine-skill wordt gepubliceerd vanuit de bibliotheek. Bij Enterprise wacht een skill die een schrijftool toevoegt tot twee bij naam genoemde personen deze met hun passkeys goedkeuren, en de indiener kan niet een van hen zijn. Een goedgekeurde versie draait vervolgens in shadow, daarna in canary voor één eenheid achter benoemde gates, daarna voor iedereen, en stopt zichzelf als niet aan een gate wordt voldaan. Als uw plug-in en een Skills Engine-skill van elkaar afhankelijk zijn, publiceer dan eerst de skill en laat deze iedereen bereiken voordat de plug-inrelease die de skill aanroept de pilot verlaat.

Kanalen en installaties

Zodra een release de pilot heeft doorlopen en alle eenheden heeft bereikt, wordt deze aangeboden op een kanaal, en elke eenheid kiest haar eigen kanaal. De beheerder van de eenheid stemt in met elke overstap. De pagina Kanalen en installaties toont welke eenheden welke versie draaien, met foutpercentages uitsluitend als aantallen: u ziet hoe uw extensie zich gedraagt, nooit wat iemand ermee heeft gedaan.

Kanalen en installaties
Kanalen en installaties
Welke eenheden welke versie van carrier-sync draaien, met een terugdraaiactie geopend voor één eenheid. Let op wat het venster zegt dat er verandert, wat blijft, en dat er een tweede persoon voor nodig is: de eigen beheerder van de eenheid.

Onze plug-in carrier-sync draait drie versies tegelijk, en dat is normaal. De meeste eenheden gebruiken de huidige release, één eenheid blijft op een oudere versie op een kanaal dat tot een vermelde datum wordt aangehouden, en een release candidate staat op een kanaal dat nog niemand heeft gekozen. Verzet u daar niet tegen; een eenheid die stabiliteit nodig heeft voor een audit, heeft daar recht op.

De logboeken en statistieken van uw extensie

De pagina met logs en metrics voor uw pack is beperkt tot uw eigen workloads, in de eenheden waarin u mag kijken. U kunt filteren op eenheid en omgeving, en u ziet aantallen, tijden en statussen.

Logs en metrics van uw pack
Logs en metrics van uw pack
De eigen logs en metrics van Cold chain, gefilterd op de pilot in Rotterdam. Kijk naar de logregels: de persoon die een afwijking meldde, is verborgen, en de tekst van de claimnotitie wordt helemaal nooit gelogd.

Persoonsgegevens worden vervangen voordat een regel wordt geschreven, en klantinhoud zoals claimtekst, e-mail of de inhoud van documenten wordt nooit naar logs geschreven. Logs worden 14 dagen bewaard. De organisatie wordt bepaald door de gateway, nooit door uw query, dus een query die een andere organisatie noemt, wordt geweigerd met TENANT_BOUNDARY. De assistent in het dock kan dezelfde logs samen met u lezen, en alleen deze: toen ik vroeg waarom afwijkingsrecords op een ochtend te laat binnenkwamen, herleidde de assistent 18 minuten aan nieuwe pogingen tot dubbele metingen van de stroomvoorziening van één kade.

Terugdraaien

Er zijn twee soorten rollback, en beide zijn gereviewde wijzigingen in plaats van schakelaars.

Bij het terugdraaien van een omgeving wordt de vorige versie gebruikt. Elke omgeving bewaart deze 30 dagen. De rollback wordt voorbereid als een wijziging van de release, toont vooraf wat deze zal doen en vereist een tweede persoon; na goedkeuring draait de pipeline in ongeveer een minuut terug. Elke rollback wordt getimed, net als elke oefening, dus oefen er een voordat u deze nodig hebt. Voor het terugdraaien van één eenheid gebruikt u de pagina Kanalen en installaties. Het terugdraaivenster vermeldt wat er verandert (die eenheid draait weer de oudere versie, en het foutpercentage ervan wordt een uur lang gevolgd), wat blijft (de andere eenheden, en de instellingen en records van de eenheid), de reden, en wie de tweede persoon is: de beheerder van die eenheid.

Instellingen en records blijven behouden bij een rollback, dus plan elke release in de veronderstelling dat de vorige versie opnieuw kan draaien op de gegevens die de nieuwere versie heeft geschreven. Dat is de praktische reden om migraties additief te houden binnen een release die u mogelijk terugdraait, en de reden dat wij twee personen vragen om elke migratie goed te keuren. Voor een modelwijziging geldt hetzelfde: een reviewer kan, en moet, om het rollbackplan van een graph change request vragen voordat deze wordt goedgekeurd.

Skills worden voorzichtiger teruggedraaid. Het terugzetten van het live-label naar een eerdere versie is één stap, en runs die al bezig zijn, worden voltooid op de versie waarmee ze begonnen.

Een versie uitfaseren

Een release wordt, eenmaal gemaakt, nooit bewerkt. Een versie die niet meer gebruikt mag worden, wordt ingetrokken, en een correctie wordt uitgebracht als een nieuw versienummer. De eigen releasekanalen van de SDK volgen dezelfde gewoonte: een slechte SDK-versie wordt teruggetrokken, nooit vervangen door andere inhoud onder hetzelfde nummer. Neem dit over, want een versienummer dat twee verschillende builds kan betekenen, maakt elk bewijsstuk erover waardeloos.

Het intrekken van een plug-in of pack stopt nieuwe installaties. Eenheden behouden de versie die ze draaien totdat ze overstappen, dus intrekken is een signaal en een deadline, geen uitschakelaar. Laat de beheerders van de eenheden weten naar welke versie ze moeten overstappen en wanneer.

Het buiten gebruik stellen van een skill volgt hetzelfde idee met één extra stap. De Skills Engine verplaatst elke resterende aanroeper naar een vervanging nadat de cases van de vervanging zijn uitgevoerd, stopt nieuwe runs, en bewaart de versies, cases en verzegelde runrecords, zodat de skill kan worden teruggehaald als de vervanging verkeerd blijkt te zijn.

Een release-checklist

Dit is de lijst die wij doorlopen vóór elke release van Cold chain. Hij is kort omdat het platform het meeste ervan voor ons controleert.

  1. Versies komen overeen: het manifest, pack.json, en het kennismodel als dat is gewijzigd.
  2. Elke gate is lokaal groen, vanaf een schone basis, en van elke nieuwe test is aangetoond dat deze eerst faalde.
  3. De pagina Manifest en machtigingen toont geen uitbreiding, of de uitbreiding is wat wij bedoelden en de reviewers weten waarom.
  4. Elke migratie is een nieuw genummerd bestand, afgebakend, en zonder fouten toegepast op een wegwerpdatabase.
  5. scripts/ci/required-env vermeldt elke variabele die de service nodig heeft, en de deployment stelt elke variabele in.
  6. Het rollbackplan staat beschreven in de wijziging, ook voor elke modelwijziging.
  7. Twee reviewers die niet de auteur zijn, zijn deze week beschikbaar.

Het laatste punt klinkt triviaal. Het is het punt dat meer van onze releases heeft vertraagd dan alle gates bij elkaar.