Prihlásiť saRezervovať brífing

Kapitola 2.28

Vydanie vášho rozšírenia

Ako sa zásuvný modul alebo balík dostane od úspešnej zostavy k jednotkám, ktoré ho spúšťajú, a ako sa z nich opäť stiahne. Verzie, kontrola pred vydaním, kanály a inštalácie, podpisovanie, schvaľovanie zmien, záznam o identite doručenia, migrácie, návrat k predchádzajúcej verzii (rollback) a vyradenie verzie.

Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

18 min čítania

Cold chain 0.4.0 bolo prvé naše vydanie, ktoré žiadalo viac než to predchádzajúce. Pridalo odosielanie pošty a jednu externú adresu pre upozornenia z chladiarenských kontajnerov. Zostavenie bolo zelené, testy prešli na všetkých troch syntetických pobočkách, a napriek tomu zostalo dva dni v dev space, kým dvaja ľudia čítali, čo požaduje, a tretí schválil adresu. Presne takto má vydávanie v Nexus pôsobiť: kód je tá jednoduchšia časť a vydaním sú dôkazy a schválenia.

Táto kapitola pokrýva všetko medzi zeleným zostavením a verziou spustenou pre všetky jednotky, ako aj spôsoby návratu späť. Samotná cesta povýšenia, z dev space do staging, na pilotnú jednotku a na všetky jednotky, je predstavená v kapitole 2.24, Budovanie vlastnej vertikály od začiatku do konca, a jej brány tu nebudem opakovať. Celý proces rámcuje jedno pravidlo. Nasadenie prebieha výlučne cez kanály vydaní inštalácie. Pre urgentnú opravu neexistujú žiadne zadné dvierka a nikto neupravuje bežiaci obraz ručne.

Verzie

Pri vydaní balíka sa menia tri čísla verzií a oplatí sa ich v hlave držať oddelene.

Čo Kde sa nachádza Príklad Pravidlo
Plugin version v nexus.manifest.json 0.4.0 Sémantická verzia; prípona predbežného vydania, napríklad -rc.1, je povolená
Balík version v pack.json 0.4.0 Mení sa spolu s pohľadmi, slovami a klastrami balíka
Znalostný model Vlastná verzia modelu 1.3 na 1.4 Mení sa iba prostredníctvom žiadosti o zmenu grafu

Vývojové zostavenie nesie príponu 0.4.0-dev, kým sa nedostane do staging. Keď sa plugin a balík dodávajú spolu, udržiavajte ich verzie rovnaké; ušetríte si tým pri každej revízii vydania spor o to, ku ktorému číslu dôkazy patria.

Dve ďalšie verzie sú pevne určené, nie zvolené. Verzia šablóny balíka (domain-pack@1.6.0 pre Cold chain) sa stanoví pri vytvorení balíka a mení sa iba ako revidovaná zmena. SDK (súprava na vývoj softvéru) sa inštaluje v presnej verzii, nikdy nie v rozsahu, aby rovnaké zostavenie dalo budúci mesiac rovnaký výsledok:

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

Aj zručnosti Skills Engine majú verzie, správajú sa však inak. Každá zverejnená verzia je nemenná a live, canary a shadow sú štítky na verziách. Návrat späť presunie štítok a behy, ktoré už prebiehajú, sa dokončia na verzii, na ktorej začali.

Pred požiadaním o kontrolu: manifest

Stránka Manifest a oprávnenia porovnáva, čo deklaruje toto vydanie, s posledným vydaním: jeho rozsahy, úložiská, odchádzajúce adresy a profil sandboxu. Prečítajte si ju skôr, než niekoho požiadate o revíziu, pretože vám presne povie, čo budú revízori žiadaní prijať.

Manifest a povolenia
Manifest a povolenia
Čo deklaruje Cold chain 0.4.0 oproti 0.3.2. Všimnite si dva riadky označené ako rozširujúce, odosielanie pošty a jednu externú adresu, a štítok, ktorý hovorí, že vydanie sa neposunie ďalej z dev space, kým ich neprijmú dvaja revízori.

Vydanie, ktoré žiada viac, než predtým deklaroval jeho manifest, sa zadrží na mieste s MANIFEST_SCOPE_WIDENED, kým širší manifest neprijmú dvaja revízori. Externá adresa navyše potrebuje schválenie toho, kto u zákazníka zodpovedá za externé adresy; toto schválenie sa udeľuje na pevne stanovené obdobie a naše platilo 12 mesiacov. Máte dve možnosti: odstrániť tieto riadky alebo požiadať o revíziu. Stránka ponúka obe tlačidlá.

Každý riadok na tejto stránke sa za behu vynucuje, nielen reviduje. Každé volanie nástroja sa kontroluje voči deklarovaným rozsahom, externá adresa je zablokovaná, ak nie je uvedená, a profil sandboxu nepovoľuje žiadnu inú sieť. Plugin, ktorý sa pokúsi dostať k niečomu, čo nedeklaroval, je odmietnutý a jedinou nápravou je nové vydanie, ktoré to deklaruje.

Kontrola pred vydaním

Stránka Revízia vydania zhromažďuje dôkazy k jednému vydaniu v jednej tabuľke pre revízora, ktorý nie je autorom.

Revízia vydania
Kontrola pred vydaním
Pohľad druhého revízora na Cold chain 0.4.0 s tabuľkou dôkazov, rozdielom rozsahov a komentármi. Všimnite si štítok vpravo: autor nemôže schváliť vlastné vydanie.
Dôkaz Čo ukázal pre 0.4.0
Testy 66 zo 66 na troch syntetických pobočkách
Kontroly kvality Dokumentácia a kód sú v súlade
Politika Každý pohľad iba zužuje; osobné polia sú predvolene vypnuté
Podpisy Obraz a balík podpísané pipeline
Rozdiel rozsahov Pridáva odosielanie pošty a jednu externú adresu s jej schválením
Kompatibilita Verzia platformy a verzia základného balíka, voči ktorým bolo testované
Zmena modelu Skúšobný beh žiadosti o zmenu grafu: 1 284 premenovaných prepojení, nič nebolo odstránené

Pod tabuľkou sú komentáre k zmene a pôvod: ktorá pipeline ju zostavila, z ktorej zmeny, digest obrazu a šablóna. Revízori schvaľujú pomocou svojho prístupového kľúča (passkey). Schvaľujú dvaja revízori, ktorí nie sú autormi, a pipeline potom presunie vydanie do staging. Autor sa nikdy nepočíta ako revízor a pokus o to je odmietnutý s NEEDS_SECOND_PERSON. Žiadosť o revíziu vyprší po 3 dňoch.

Na otázky revízorov odpovedajte v komentároch, nie v okne chatu. Počas našej revízie sa náš compliance officer pýtal, prečo bola suma nároku klasifikovaná ako obchodná, a druhý revízor žiadal plán návratu pre zmenu modelu. Obe odpovede sú teraz súčasťou záznamu vydania, kde sa bude pozerať ďalší revízor.

Schválenia politiky zmien

Revízia vydania pokrýva vydanie ako celok. Blok changePolicy v manifeste ide ďalej: určuje, ktoré triedy zmien nasaditeľných súčastí vášho pluginu vyžadujú schválenie a od koľkých ľudí.

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

Tri triedy sú website (webová aplikácia), bff (backend pre frontend) a migration (migrácia databázy). Každá trieda uvedená v classes musí mať vlastný počet v approvals, od 1 do 10. Trieda, ktorú vynecháte, nie je riadená a schéma vás núti zapísať to ako voľbu, nie dospieť k tomu opomenutím. Pri migráciách žiadame dve schválenia, pretože migrácia je jediná zmena, ktorú je ťažké vrátiť.

Schválenia sa počítajú podľa rôznych osôb a navrhovateľ medzi nich nikdy nepatrí. Pravidlá, ktoré to zabezpečujú, sa oplatí poznať, pretože každé má svoje odmietnutie:

  • Schválenie od osoby, ktorá zmenu navrhla, je odmietnuté s TRUST_APPROVAL_SELF_APPROVAL.
  • Osoba, ktorá zmenu danej triedy nesmie vykonať vôbec, je odmietnutá s CHANGE_CLASS_NOT_PERMITTED.
  • Ak je ktorýkoľvek commit v zmene podpísaný identitou agenta organizácie, kvórum je obvyklé minimum plus jedna a vlastný hlas agenta sa nepočíta.
  • Každé schválenie zaznamená diff a head, ktoré videlo. Ak sa zmena po poslednom schválení posunie, jej zlúčenie je odmietnuté s HASH_MISMATCH a schválenia sa musia pre nový obsah zozbierať znova.

Toto tretie pravidlo je dôležité, ak vyvíjate pomocou nástroja na programovanie s AI (umelá inteligencia), ako popisuje kapitola 2.26, Vývoj s nástrojmi na programovanie s AI. Práca, ktorú napísal agent, potrebuje o jedno ľudské schválenie viac než práca, ktorú napísal človek. Počítajte s tým.

Podpisovanie a overovanie

Každý obraz a balík je podpísaný pipeline, ktorá ho zostavila, a podpísaný obraz je jednou z brán do staging. Dev space od začiatku spúšťa iba podpísané obrazy. V edícii Enterprise administrátor nastaví každý namespace tak, aby nepodpísané obrazy buď zaznamenával, alebo odmietal, a namespaces prepína na odmietanie postupne jeden po druhom, takže v produkcii nakoniec bežia iba obrazy, ktoré pipeline zostavila a podpísala. Podpisovanie je súčasťou zostavenia, nie niečo, čo pridáte pred vydaním.

Pravidlo, ktoré sa tým všetkým tiahne, znie: podpis, ktorý zlyhá, je odmietnutím, nikdy nie varovaním. Kontrola, ktorá dostane SIG_INVALID, sa zastaví. Neprejde na nepodpísanú verziu a nepokračuje s poznámkou v logu, pretože varovanie v logu zostavenia je priepustkou pre každého, kto ho nečítal.

Rovnaké pravidlo platí pre všetko, čo odovzdávate na médiách. Zapečatený balík pre zákazníka s air-gapped prostredím sa pred rozbalením čohokoľvek overí voči vášmu verejnému kľúču a kapitola 2.25, Vývoj pre jednotlivé edície, ukazuje príslušný príkaz.

Identita doručenia

Plugin sa dodáva prostredníctvom viacerých vecí, z ktorých každá má názov: jeho repozitáre, podpisový kľúč, namespace nasadenia, prefix registra, databázová schéma, súbor domén a politika zmien. Ktorákoľvek z nich je miestom, kde by sa dva pluginy mohli dostať do kolízie alebo kde by sa jeden plugin mohol odchýliť. Identita dodávky je jeden podpísaný záznam na plugin, ktorý ich všetky obsahuje, takže každá kontrola na ceste vydania číta rovnakú odpoveď a pri nezhode odmietne.

Svoju časť prispievate výlučne cez manifest: schema, db, domains, changePolicy a URL repozitára. Platforma doplní zvyšok záznamu a podpíše ho. Nikdy sami neurčujete svoj namespace, prefix registra ani podpisový kľúč. Tie vám sú pridelené a manifest, ktorý by sa ich pokúsil deklarovať, by vznášal tvrdenie, ktorému by kontroly potom museli neveriť.

Podpísaný záznam obsahuje jedenásť polí: slug pluginu, vlastniacu organizáciu, organizáciu, ktorá ho zostavuje, jeho repozitáre, názov jeho podpisového kľúča, jeho namespace nasadenia, jeho prefix registra, jeho databázovú schému, jeho domény, jeho politiku zmien a krátky zoznam starších názvov obrazov, ktoré používal predtým, ako existoval jeho prefix registra. Tento posledný zoznam sa môže iba zmenšovať. Keďže je podpísaný, nový podpis môže položku odstrániť, ale nič ju nemôže potichu pridať. Podpis je Ed25519 nad štandardnou kanonickou formou JSON týchto jedenástich polí, takže záznam s "Tomás" alebo "Sinéad" sa všade overí rovnako.

Ak vydanie nezodpovedá svojmu záznamu, platí prvé odmietnutie:

Kód Kedy HTTP
DELIVERY_IDENTITY_MISSING Pre plugin neexistuje žiadny záznam 403
DELIVERY_PATH_REFUSED Push obrazu mimo prefixu registra, ktorý nie je na podpísanom zozname starších názvov 403
NAMESPACE_MISMATCH Nasadenie zacielené na iný namespace 403
IMAGE_NAME_COLLISION Názov obrazu, ktorý si už nárokuje iný plugin 409
CHANGE_CLASS_NOT_PERMITTED Trieda zmeny, ktorú politika neriadi 403

IMAGE_NAME_COLLISION je to, ktoré ľudí prekvapí. Zvoľte iný názov a nikdy žiadny nepoužívajte opakovane: zdieľaný názov obrazu znamená, že povýšenie jedného pluginu môže presunúť pody iného pluginu.

Migrácie, potvrdené a s vymedzeným rozsahom

Migrácia sa dodáva vo vnútri obrazu vášho pluginu a spúšťa sa pred štartom novej verzie, prostredníctvom jediného nástroja na spúšťanie migrácií v SDK, nexus-migrate. Vlastný nástroj na aplikovanie nepíšete. Skôr než sa akékoľvek vydanie môže posunúť, ten istý nástroj aplikuje vaše migrácie po jednom súbore na dočasnú databázu, takže migrácia, ktorá zlyhá, zlyhá tam. Tieňové zostavenie šablóny volá tento nástroj raz pre každý súbor, v poradí, a každý súbor zaznamená tak, ako to urobí produkcia.

Pravidlá nástroja sú tie, ktoré kontrolujú brány, zapísané ako kód:

  1. Pripája sa ako rola migrátora vašej schémy a každý súbor spúšťa ako vlastník schémy. Akékoľvek iné prihlásenie, predovšetkým superuser, je odmietnuté. Súbor, ktorý sa sám pokúsi prepnúť roly, je odmietnutý ešte predtým, ako sa čokoľvek spustí.
  2. Súbor tenancy s číslom 0 sa po aplikovaní už nikdy neupravuje. Zmena tenancy dostane vlastný revízny súbor, 000_tenancy_r<N>.sql, ktorý za vás napíše nexus-tenancy render --revision <N>.
  3. Za normálnych okolností nástroj vlastní transakciu každého súboru a odmietne v nej BEGIN alebo COMMIT. Súbor, ktorý spravuje vlastné transakcie, deklaruje, že sa spúšťa po jednotlivých príkazoch, a potom každý BEGIN, ktorý otvorí, musí mať svoj pár.
  4. Vedie register, jeden riadok na súbor, so SHA-256 súboru a spôsobom, akým bol spustený. Aplikovaný súbor sa nikdy nemení na mieste; zmena je nový očíslovaný súbor.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Ohraničený znamená, že každá nová tabuľka obsahuje organization_id, owner_user_id a business_unit_id, plus stĺpec so značkou is_demo, pokiaľ gates/demo-exempt.json tabuľku s uvedením dôvodu neoslobodí, s primárnym kľúčom, ktorý začína organizáciou, a cudzími kľúčmi, ktoré ju nesú, a s vynútenou bezpečnosťou na úrovni riadkov. Brána migrations-are-scoped kontroluje tieto pravidlá vo všetkých súboroch a migrations-commit-what-they-open overuje, že každý súbor potvrdí to, čo otvorí. Druhá brána existuje preto, lebo migrácia, ktorá sa potichu vrátila späť, raz skončila s kódom 0 a tabuľka, ktorú mala vytvoriť, nikdy neexistovala.

Ku každému vydaniu patrí ešte jeden súbor. scripts/ci/required-env vypíše premenné prostredia, ktoré vaša služba potrebuje na spustenie, ako pole JSON prevzaté z vášho načítavača konfigurácie. Cesta vydania ho spustí a odmietne vydanie, ktorého nasadenie nenastavuje každú z nich, takže chýbajúca premenná sa zachytí pred vydaním, nie až podom, ktorý sa nespustí.

node scripts/ci/required-env

Vydávanie zručností

Dva druhy zručností sa k ľuďom dostávajú rôznymi cestami, preto ich vydávajte rozdielne.

Zručnosť z manifestu, typovaný riadok vo vašom skills[] pluginu, sa dodáva s pluginom a prechádza rovnakým povýšením ako jeho zvyšok. Onboarding pri každom vydaní synchronizuje celú sadu zručností do registra. Ak zručnosť zo sady vynecháte, bude vypnutá, a v edícii Enterprise synchronizácia s jednou chybnou zručnosťou neprevezme žiadnu z nich, takže ďalej beží predchádzajúca verzia namiesto polovice novej.

Zručnosť Skills Engine sa publikuje z knižnice. V edícii Enterprise zručnosť, ktorá pridáva nástroj na zápis, čaká, kým ju svojimi prístupovými kľúčmi (passkeys) schvália dve menovite určené osoby, pričom navrhovateľ nemôže byť jednou z nich. Schválená verzia potom beží v tieňovom režime, potom v režime canary pre jednu jednotku za menovite určenými bránami, potom pre všetkých a ak niektorá brána nie je splnená, sama sa zastaví. Ak sú váš plugin a zručnosť Skills Engine navzájom závislé, najprv publikujte zručnosť a nechajte ju dostať sa ku všetkým, až potom môže vydanie pluginu, ktoré ju volá, opustiť pilotnú fázu.

Kanály a inštalácie

Keď vydanie prejde pilotnou fázou a dostane sa do všetkých jednotiek, ponúka sa v kanáli a každá jednotka si svoj kanál vyberie. Jej administrátor súhlasí s každým presunom. Stránka Kanály a inštalácie zobrazuje, ktoré jednotky používajú ktorú verziu, pričom chybovosť uvádza iba ako počty: vidíte, ako sa vaše rozšírenie správa, nikdy však nie to, čo s ním ktokoľvek robil.

Kanály a inštalácie
Kanály a inštalácie
Ktoré jednotky používajú ktorú verziu carrier-sync, s otvoreným vrátením pre jednu jednotku. Všimnite si, čo podľa modálneho okna sa zmení, čo zostane, a že je potrebná druhá osoba, vlastný administrátor jednotky.

Náš plugin carrier-sync beží súčasne v troch verziách a je to normálne. Väčšina jednotiek používa aktuálne vydanie, jedna jednotka zostáva na staršej verzii v kanáli udržiavanom do stanoveného dátumu a kandidát na vydanie je v kanáli, ktorý si zatiaľ nikto nevybral. Nebojujte proti tomu; jednotka, ktorá potrebuje stabilitu kvôli auditu, má na ňu nárok.

Záznamy (logy) a metriky vášho rozšírenia

Stránka protokolov a metrík vášho balíka je obmedzená na vaše vlastné úlohy v jednotkách, do ktorých smiete nahliadať. Môžete filtrovať podľa jednotky a prostredia a vidíte počty, časy a stavy.

Protokoly a metriky vášho balíka
Protokoly a metriky vášho balíka
Vlastné protokoly a metriky balíka Cold chain, filtrované na pilot v Rotterdame. Pozrite sa na riadky protokolu: osoba, ktorá nahlásila odchýlku, je skrytá a text poznámky k reklamácii sa do protokolu nikdy nezapisuje.

Osobné polia sa nahradia pred zapísaním riadku a obsah zákazníkov, ako je text reklamácie, pošta alebo obsah dokumentov, sa do protokolov nikdy nezapisuje. Protokoly sa uchovávajú 14 dní. Organizáciu nastavuje brána, nikdy nie váš dotaz, takže dotaz, ktorý uvádza inú organizáciu, sa odmietne s TENANT_BOUNDARY. Asistent v paneli môže čítať tie isté protokoly spolu s vami, a iba tieto: keď som sa ho opýtal, prečo jedného rána prišli záznamy o odchýlkach neskoro, vystopoval 18 minút opakovaných pokusov k duplicitným meraniam z napájania jedného nábrežia.

Návrat k predchádzajúcej verzii (rollback)

Existujú dva druhy vrátenia a obe sú posudzované zmeny, nie prepínače.

Vrátenie prostredia používa predchádzajúcu verziu. Každé prostredie ju uchováva 30 dní. Vrátenie sa pripraví ako zmena vydania, zobrazí ukážku toho, čo vykoná, a vyžaduje druhú osobu; po schválení pipeline vykoná vrátenie približne za minútu. Každé vrátenie sa meria, rovnako ako každé cvičenie, preto si ho precvičte skôr, než ho budete potrebovať. Vrátenie jednej jednotky sa vykonáva na stránke Kanály a inštalácie. Modálne okno vrátenia uvádza, čo sa zmení (daná jednotka opäť používa staršiu verziu a jej chybovosť sa hodinu sleduje), čo zostane (ostatné jednotky a nastavenia a záznamy jednotky), dôvod a kto je druhou osobou: administrátor danej jednotky.

Nastavenia a záznamy sa pri vrátení zachovávajú, preto každé vydanie plánujte s predpokladom, že predchádzajúca verzia môže opäť bežať nad údajmi, ktoré zapísala novšia. To je praktický dôvod, prečo udržiavať migrácie v rámci vydania, ktoré možno budete vracať, iba doplnkové, a dôvod, prečo žiadame, aby každú schválili dve osoby. Zmena modelu je rovnaká: posudzovateľ môže, a mal by, pred schválením požiadať o plán vrátenia požiadavky na zmenu grafu.

Zručnosti sa vracajú šetrnejšie. Presunutie označenia live späť na staršiu verziu je jeden krok a už prebiehajúce behy sa dokončia na verzii, s ktorou začali.

Vyradenie verzie

Vydanie sa po vytvorení nikdy neupravuje. Verzia, ktorá by sa už nemala používať, sa stiahne a oprava sa dodá ako nové číslo verzie. Vlastné kanály vydaní SDK dodržiavajú rovnaký zvyk: chybná verzia SDK sa stiahne (yank), nikdy sa nenahradí iným obsahom pod rovnakým číslom. Osvojte si to, pretože číslo verzie, ktoré môže znamenať dve rôzne zostavenia, robí každý dôkaz o nej bezcenným.

Stiahnutie pluginu alebo balíka zastaví nové inštalácie. Jednotky si ponechajú verziu, ktorú používajú, kým neprejdú inam, takže stiahnutie je signál a termín, nie vypínač. Oznámte administrátorom jednotiek, na ktorú verziu majú prejsť a dokedy.

Vyradenie zručnosti sa riadi rovnakou myšlienkou s jedným krokom navyše. Skills Engine po spustení testovacích prípadov náhrady presunie všetkých zostávajúcich volajúcich na náhradu, zastaví nové behy a uchová verzie, prípady a zapečatené záznamy o behoch, takže zručnosť možno obnoviť, ak sa náhrada ukáže ako chybná.

Kontrolný zoznam pre vydanie

Toto je zoznam, ktorý čítame pred každým vydaním Cold chain. Je krátky, pretože väčšinu z neho za nás kontroluje platforma.

  1. Verzie sa zhodujú: manifest, pack.json a znalostný model, ak sa zmenil.
  2. Každá brána je lokálne zelená, od čistého stavu, a každý nový test najprv preukázateľne zlyhal.
  3. Stránka Manifest a oprávnenia nezobrazuje žiadne rozšírenie, alebo je rozšírenie presne to, čo sme zamýšľali, a posudzovatelia vedia prečo.
  4. Každá migrácia je nový očíslovaný súbor s vymedzeným rozsahom, bez problémov aplikovaný na dočasnú databázu.
  5. scripts/ci/required-env uvádza každú premennú, ktorú služba potrebuje, a nasadenie nastavuje každú z nich.
  6. Plán vrátenia je zapísaný v zmene, vrátane akejkoľvek zmeny modelu.
  7. Tento týždeň sú k dispozícii dvaja posudzovatelia, ktorí nie sú autormi.

Posledná položka znie triviálne. Práve ona však zdržala viac našich vydaní než všetky brány dohromady.