Přihlásit seDomluvit prezentaci

Kapitola 2.28

Vydání vašeho rozšíření

Jak plugin nebo balíček putuje od úspěšného sestavení do jednotek, které jej spouštějí, a jak se opět stahuje. Verze, kontrola před vydáním, kanály a instalace, podepisování, schvalování změn, záznam identity doručení, migrace, vrácení změn (rollback) a vyřazení verze.

Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

18 min čtení

Cold chain 0.4.0 bylo naše první vydání, které požadovalo více než to předchozí. Přidalo odesílání pošty a jednu externí adresu pro upozornění z chladicích kontejnerů. Sestavení bylo zelené, testy prošly na všech třech syntetických pobočkách, a přesto zůstalo dva dny ve vývojovém prostoru, zatímco dva lidé četli, co požaduje, a třetí schválil adresu. Přesně takto má vydávání v Nexus působit: kód je ta snadná část a vydání tvoří důkazy a schválení.

Tato kapitola pokrývá vše mezi zeleným sestavením a verzí spuštěnou pro všechny jednotky, a také cesty zpět. Samotná cesta povýšení, z vývojového prostoru do stagingu, na pilotní jednotku a na všechny jednotky, je představena v kapitole 2.24, Sestavení vlastní vertikály od začátku do konce, a její brány zde nebudu opakovat. Vše rámuje jedno pravidlo. Nasazení probíhá výhradně přes kanály vydání dané instalace. Pro naléhavou opravu neexistují žádná zadní vrátka a nikdo neupravuje běžící image ručně.

Verze

Ve vydání balíčku se mění tři čísla verzí a vyplatí se je v hlavě držet odděleně.

Co Kde se nachází Příklad Pravidlo
Plugin version v nexus.manifest.json 0.4.0 Sémantická verze; je povolena přípona předběžné verze, například -rc.1
Balíček version v pack.json 0.4.0 Mění se s pohledy, slovy a clustery balíčku
Znalostní model Vlastní verze modelu 1.3 na 1.4 Mění se pouze prostřednictvím žádosti o změnu grafu

Vývojové sestavení nese příponu 0.4.0-dev, dokud nedosáhne stagingu. Pokud se plugin a balíček dodávají společně, udržujte jejich verze shodné; ušetříte si tak při každé kontrole vydání spor o to, ke kterému číslu důkazy patří.

Dvě další verze se nevybírají, ale jsou pevně připnuté. Verze šablony balíčku (domain-pack@1.6.0 pro Cold chain) se stanoví při vytvoření balíčku a mění se pouze jako zkontrolovaná změna. SDK (sada pro vývoj softwaru) se instaluje v přesné verzi, nikdy v rozsahu, aby stejné sestavení dalo stejný výsledek i příští měsíc:

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

Dovednosti Skills Engine mají také verze a chovají se odlišně. Každá publikovaná verze je neměnná a live, canary a shadow jsou štítky na verzích. Návrat zpět přesouvá štítek a již probíhající běhy se dokončí na verzi, se kterou začaly.

Než požádáte o kontrolu: manifest

Stránka Manifest a oprávnění porovnává, co toto vydání deklaruje, s posledním vydáním: jeho rozsahy, úložiště, odchozí adresy a profil sandboxu. Přečtěte si ji dříve, než někoho požádáte o kontrolu, protože vám přesně řekne, co budou kontroloři žádáni přijmout.

Manifest a oprávnění
Manifest a oprávnění
Co Cold chain 0.4.0 deklaruje oproti 0.3.2. Všimněte si dvou řádků označených jako rozšíření, odesílání pošty a jedné externí adresy, a štítku, který uvádí, že se vydání nepohne dál z vývojového prostoru, dokud je nepřijmou dva kontroloři.

Vydání, které požaduje více, než jeho manifest dříve deklaroval, je zadrženo tam, kde je, s MANIFEST_SCOPE_WIDENED, dokud dva kontroloři nepřijmou rozšířený manifest. Externí adresa navíc vyžaduje schválení toho, kdo u zákazníka spravuje externí adresy; toto schválení se uděluje na pevně stanovenou dobu a naše platilo 12 měsíců. Máte dvě cesty vpřed: odebrat dané řádky, nebo požádat o kontrolu. Stránka nabízí obě tlačítka.

Každý řádek na této stránce se za běhu vynucuje, nejen kontroluje. Každé volání nástroje se ověřuje vůči deklarovaným rozsahům, externí adresa je blokována, pokud není uvedena, a profil sandboxu nepovoluje žádnou jinou síť. Plugin, který se pokusí dosáhnout na něco, co nedeklaroval, je odmítnut a jedinou nápravou je nové vydání, které to deklaruje.

Kontrola před vydáním

Stránka Kontrola vydání shromažďuje důkazy k jednomu vydání do jedné tabulky pro kontrolora, který není jeho autorem.

Kontrola vydání
Kontrola před vydáním
Pohled druhého kontrolora na Cold chain 0.4.0 s tabulkou důkazů, rozdílem rozsahů a komentáři. Všimněte si štítku vpravo: autor nemůže schválit své vlastní vydání.
Důkaz Co ukázal pro 0.4.0
Testy 66 z 66, na třech syntetických pobočkách
Kontroly kvality Dokumentace a kód se shodují
Politika Každý pohled pouze zužuje; osobní pole jsou ve výchozím stavu vypnutá
Podpisy Image a balíček podepsané pipeline
Rozdíl rozsahů Přidává odesílání pošty a jednu externí adresu včetně jejího schválení
Kompatibilita Verze platformy a verze základního balíčku, proti kterým bylo testováno
Změna modelu Zkušební běh žádosti o změnu grafu: 1 284 přejmenovaných vazeb, nic neodebráno

Pod tabulkou jsou komentáře ke změně a původ: která pipeline ji sestavila, z jaké změny, digest image a šablona. Kontroloři schvalují pomocí svého přístupového klíče (passkey). Schvalují dva kontroloři, kteří nejsou autorem, a pipeline poté vydání přesune do stagingu. Autor se nikdy nepočítá jako kontrolor a takový pokus je odmítnut s NEEDS_SECOND_PERSON. Žádost o kontrolu vyprší po 3 dnech.

Na otázky kontrolorů odpovídejte v komentářích, ne v chatovacím okně. Během naší kontroly se náš pracovník pro compliance zeptal, proč byla výše nároku klasifikována jako obchodní údaj, a druhý kontrolor požádal o plán návratu pro změnu modelu. Obě odpovědi jsou nyní součástí záznamu vydání, kam se podívá další kontrolor.

Schválení podle politiky změn

Kontrola vydání pokrývá vydání jako celek. Blok changePolicy v manifestu jde dál: určuje, které třídy změn nasaditelných částí vašeho pluginu vyžadují schválení a od kolika lidí.

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

Tři třídy jsou website (webová aplikace), bff (backend pro frontend) a migration (migrace databáze). Každá třída uvedená v classes musí mít v approvals svůj vlastní počet, od 1 do 10. Třída, kterou vynecháte, není řízena, a schéma vás nutí zapsat to jako vědomou volbu, nikoli k tomu dojít opomenutím. U migrací požadujeme dvě schválení, protože migrace je jediná změna, kterou je obtížné vzít zpět.

Schválení se počítají podle různých osob a navrhovatel mezi ně nikdy nepatří. Pravidla, která to zajišťují, stojí za to znát, protože každé z nich má své odmítnutí:

  • Schválení od osoby, která změnu navrhla, je odmítnuto s TRUST_APPROVAL_SELF_APPROVAL.
  • Osoba, která změnu dané třídy vůbec nesmí provést, je odmítnuta s CHANGE_CLASS_NOT_PERMITTED.
  • Pokud je kterýkoli commit ve změně podepsán identitou agenta organizace, kvórum je obvyklé minimum plus jedna a vlastní hlas agenta se nepočítá.
  • Každé schválení zaznamenává diff a head, které vidělo. Pokud se změna po posledním schválení posune, její sloučení je odmítnuto s HASH_MISMATCH a schválení je nutné pro nový obsah získat znovu.

Toto třetí pravidlo je důležité, pokud vyvíjíte s nástrojem pro programování s AI (umělou inteligencí), jak popisuje kapitola 2.26, Vývoj s nástroji pro programování s AI. Práce, kterou napsal agent, potřebuje o jedno lidské schválení více než práce, kterou napsal člověk. Počítejte s tím.

Podepisování a ověřování

Každá image a každý balíček jsou podepsány pipeline, která je sestavila, a podepsaná image je jednou z bran do stagingu. Vývojový prostor spouští od začátku pouze podepsané image. V edici Enterprise administrátor nastaví každý namespace buď na zaznamenávání nepodepsaných image, nebo na jejich odmítání, a převádí namespaces na odmítání jeden po druhém, takže produkce nakonec spouští pouze image, které pipeline sestavila a podepsala. Podepisování je součástí sestavení, nikoli něčím, co přidáte před vydáním.

Pravidlo, které prochází vším, zní: podpis, který selže, je odmítnutí, nikdy varování. Kontrola, která obdrží SIG_INVALID, se zastaví. Nepřejde na nepodepsanou verzi a nepokračuje s poznámkou v logu, protože varování v logu sestavení je pro každého, kdo ho nečetl, propustkou.

Stejné pravidlo platí pro vše, co předáváte na médiích. Zapečetěný balík pro zákazníka s air-gapped prostředím se před rozbalením čehokoli ověří proti vašemu veřejnému klíči a kapitola 2.25, Vývoj pro jednotlivé edice, ukazuje příslušný příkaz.

Identita doručení

Plugin se dodává prostřednictvím několika věcí, z nichž každá má jméno: jeho repozitářů, podpisového klíče, namespace pro nasazení, prefixu registru, databázového schématu, sady domén a zásady změn. Kterákoli z nich je místem, kde by se dva pluginy mohly střetnout nebo kde by se jeden plugin mohl odchýlit. Identita dodání je jeden podepsaný záznam na plugin, který je obsahuje všechny, takže každá kontrola na cestě vydání čte stejnou odpověď a při neshodě odmítá.

Svou část přispíváte prostřednictvím manifestu a ničeho jiného: schema, db, domains, changePolicy a URL repozitáře. Platforma doplní záznam o zbytek a podepíše jej. Nikdy sami nepojmenováváte svůj namespace, prefix registru ani podpisový klíč. Ty jsou vám přiděleny a manifest, který by se je pokusil deklarovat, by vznášel nárok, kterému by kontroly pak musely nevěřit.

Podepsaný záznam obsahuje jedenáct polí: slug pluginu, vlastnickou organizaci, organizaci, která jej sestavuje, jeho repozitáře, název jeho podpisového klíče, jeho namespace pro nasazení, jeho prefix registru, jeho databázové schéma, jeho domény, jeho zásadu změn a krátký seznam starších názvů image, které používal před vznikem svého prefixu registru. Tento poslední seznam se může pouze zkracovat. Protože je podepsán, nový podpis může položku odebrat, ale nic ji nemůže potichu přidat. Podpis je Ed25519 nad standardní kanonickou podobou JSON těchto jedenácti polí, takže záznam obsahující „Tomás“ nebo „Sinéad“ se všude ověří stejně.

Když vydání neodpovídá svému záznamu, platí první odmítnutí:

Kód Kdy HTTP
DELIVERY_IDENTITY_MISSING Pro plugin neexistuje žádný záznam 403
DELIVERY_PATH_REFUSED Odeslání image mimo prefix registru, které není na podepsaném seznamu starších názvů 403
NAMESPACE_MISMATCH Nasazení cílící na jiný namespace 403
IMAGE_NAME_COLLISION Název image, který si již nárokuje jiný plugin 409
CHANGE_CLASS_NOT_PERMITTED Třída změny, kterou zásada neřídí 403

IMAGE_NAME_COLLISION je ten, který lidi překvapí. Zvolte jiný název a nikdy žádný znovu nepoužívejte: sdílený název image znamená, že povýšení jednoho pluginu může přesunout pody jiného pluginu.

Migrace, potvrzené a s vymezeným rozsahem

Migrace se dodává uvnitř image vašeho pluginu a spouští se před startem nové verze prostřednictvím jediného spouštěče migrací v SDK, nexus-migrate. Vlastní aplikátor nepíšete. Než se jakékoli vydání může posunout, stejný spouštěč aplikuje vaše migrace soubor po souboru na dočasnou databázi, takže migrace, která selže, selže tam. Stínové sestavení šablony volá spouštěč jednou pro každý soubor, v pořadí, a zaznamenává každý soubor tak, jak to udělá produkce.

Pravidla spouštěče jsou tatáž, která kontrolují brány, zapsaná jako kód:

  1. Připojuje se jako role migrátoru vašeho schématu a každý soubor spouští jako vlastník schématu. Jakékoli jiné přihlášení, především superuživatel, je odmítnuto. Soubor, který se sám pokusí přepnout roli, je odmítnut dříve, než cokoli proběhne.
  2. Soubor tenancy s číslem 0 se po aplikaci již nikdy neupravuje. Změna tenancy dostane vlastní soubor revize, 000_tenancy_r<N>.sql, který za vás zapíše nexus-tenancy render --revision <N>.
  3. Za normálních okolností spouštěč vlastní transakci každého souboru a odmítá v ní BEGIN nebo COMMIT. Soubor, který spravuje vlastní transakce, deklaruje, že běží po příkazech, a pak musí být každé BEGIN, které otevře, spárováno.
  4. Vede evidenci, jeden řádek na soubor, se SHA-256 souboru a způsobem, jakým běžel. Aplikovaný soubor se nikdy nemění na místě; změna je nový číslovaný soubor.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Scoped znamená, že každá nová tabulka nese organization_id, owner_user_id a business_unit_id, plus sloupec značky is_demo, pokud gates/demo-exempt.json tabulku s odůvodněním nevyjme, s primárním klíčem, který začíná organizací, a cizími klíči, které ji nesou, a s vynuceným zabezpečením na úrovni řádků. Brána migrations-are-scoped kontroluje tato pravidla ve všech souborech a migrations-commit-what-they-open ověřuje, že každý soubor potvrdí to, co otevře. Druhá brána existuje proto, že migrace, která se potichu vrátila zpět, jednou skončila s kódem 0 a tabulka, kterou měla vytvořit, nikdy neexistovala.

Ke každému vydání patří ještě jeden soubor. scripts/ci/required-env vypíše proměnné prostředí, které vaše služba potřebuje ke spuštění, jako pole JSON převzaté z vašeho zavaděče konfigurace. Cesta vydání jej spustí a odmítne vydání, jehož nasazení nenastavuje každou z nich, takže chybějící proměnná je zachycena před vydáním, nikoli podem, který se nespustí.

node scripts/ci/required-env

Vydávání dovedností

Dva druhy dovedností se k lidem dostávají různými cestami, proto je vydávejte odlišně.

Dovednost manifestu, typovaný řádek v skills[] vašeho pluginu, se dodává s pluginem a prochází stejným povýšením jako jeho zbytek. Onboarding při každém vydání synchronizuje celou sadu dovedností do registru. Vynechte dovednost ze sady a bude zakázána; v edici Enterprise synchronizace s jednou chybnou dovedností nepřevezme žádnou z nich, takže dál běží předchozí verze, nikoli polovina nové.

Dovednost Skills Engine se publikuje z knihovny. Ve verzi Enterprise čeká dovednost, která přidává nástroj pro zápis, na schválení dvěma jmenovitě určenými osobami pomocí jejich přístupových klíčů (passkeys), přičemž navrhovatel nemůže být jednou z nich. Schválená verze pak běží ve stínovém režimu, poté v režimu canary pro jednu jednotku za jmenovitě určenými kontrolními branami a poté pro všechny, a pokud některá brána není splněna, sama se zastaví. Pokud jsou váš plugin a dovednost Skills Engine na sobě vzájemně závislé, publikujte nejprve dovednost a nechte ji dostat se ke všem dříve, než vydání pluginu, které ji volá, opustí pilotní provoz.

Kanály a instalace

Jakmile vydání projde pilotním provozem a dostane se do všech jednotek, je nabídnuto v určitém kanálu a každá jednotka si svůj kanál volí sama. Její správce souhlasí s každým přechodem. Stránka „Kanály a instalace“ ukazuje, které jednotky provozují kterou verzi, a chybovost uvádí pouze jako počty: vidíte, jak se vaše rozšíření chová, nikdy však, co s ním kdo dělal.

Kanály a instalace
Kanály a instalace
Které jednotky provozují kterou verzi carrier-sync, s otevřeným vrácením zpět pro jednu jednotku. Všimněte si, co podle modálního okna změní, co zůstane, a že vyžaduje druhou osobu, vlastního správce dané jednotky.

Náš plugin carrier-sync provozuje tři verze současně a je to normální. Většina jednotek používá aktuální vydání, jedna jednotka zůstává na starší verzi v kanálu udržovaném do stanoveného data a kandidát na vydání je v kanálu, který si zatím nikdo nezvolil. Nebraňte se tomu; jednotka, která potřebuje stabilitu kvůli auditu, na ni má nárok.

Protokoly a metriky vašeho rozšíření

Stránka protokolů a metrik vašeho balíčku je omezena na vaše vlastní úlohy v jednotkách, do kterých smíte nahlížet. Můžete filtrovat podle jednotky a prostředí a vidíte počty, časy a stavy.

Protokoly a metriky vašeho balíčku
Protokoly a metriky vašeho balíčku
Vlastní protokoly a metriky balíčku Cold chain, filtrované na pilotní provoz v Rotterdamu. Podívejte se na řádky protokolu: osoba, která nahlásila odchylku, je skrytá a text poznámky k reklamaci se do protokolu nikdy nezapisuje.

Osobní pole jsou nahrazena dříve, než je řádek zapsán, a obsah zákazníků, jako je text reklamací, pošta nebo obsah dokumentů, se do protokolů nikdy nezapisuje. Protokoly se uchovávají 14 dní. Organizaci určuje brána, nikdy váš dotaz, takže dotaz, který uvádí jinou organizaci, je odmítnut s TENANT_BOUNDARY. Asistent v panelu může číst stejné protokoly spolu s vámi, a pouze tyto: když jsem se ho zeptal, proč záznamy o odchylkách jednoho rána přicházely pozdě, vysledoval 18 minut opakovaných pokusů k duplicitním odečtům z napájení jednoho nábřeží.

Vrácení změn (rollback)

Existují dva druhy vrácení zpět a oba jsou kontrolovanými změnami, nikoli přepínači.

Vrácení prostředí zpět používá předchozí verzi. Každé prostředí ji uchovává 30 dní. Vrácení zpět se připraví jako změna vydání, zobrazí náhled toho, co provede, a vyžaduje druhou osobu; po schválení provede pipeline vrácení zpět přibližně za minutu. Každé vrácení zpět se měří, stejně jako každé cvičení, proto si ho vyzkoušejte dříve, než ho budete potřebovat. Vrácení jedné jednotky zpět se provádí na stránce „Kanály a instalace“. Modální okno vrácení zpět uvádí, co se změní (daná jednotka znovu provozuje starší verzi a její chybovost je hodinu sledována), co zůstane (ostatní jednotky a nastavení a záznamy dané jednotky), důvod a kdo je druhou osobou: správce dané jednotky.

Nastavení a záznamy se při vrácení zpět zachovávají, proto každé vydání plánujte s předpokladem, že předchozí verze může znovu běžet nad daty, která zapsala novější verze. To je praktický důvod, proč udržovat migrace v rámci vydání, které byste mohli vracet zpět, pouze aditivní, a důvod, proč žádáme, aby každou schválily dvě osoby. Totéž platí pro změnu modelu: recenzent může, a měl by, před schválením požádat o plán vrácení zpět u požadavku na změnu grafu.

Dovednosti se vracejí zpět šetrněji. Přesunutí štítku live zpět na dřívější verzi je jediný krok a běhy, které již probíhají, se dokončí ve verzi, ve které začaly.

Vyřazení verze

Jednou vytvořené vydání se nikdy neupravuje. Verze, která by se již neměla používat, se stáhne a oprava se dodá jako nové číslo verze. Vlastní kanály vydání SDK se řídí stejným zvykem: chybná verze SDK je stažena, nikdy nahrazena jiným obsahem pod stejným číslem. Převezměte to, protože číslo verze, které může znamenat dvě různá sestavení, znehodnocuje každý důkaz, který se k ní vztahuje.

Stažení pluginu nebo balíčku zastaví nové instalace. Jednotky si ponechávají verzi, kterou provozují, dokud nepřejdou, takže stažení je signálem a termínem, nikoli vypínačem. Sdělte správcům jednotek, na kterou verzi mají přejít a do kdy.

Vyřazení dovednosti se řídí stejnou myšlenkou s jedním krokem navíc. Skills Engine po spuštění testovacích případů náhrady přesune všechny zbývající volající na náhradu, zastaví nové běhy a ponechá verze, případy a zapečetěné záznamy běhů, aby bylo možné dovednost obnovit, pokud se náhrada ukáže jako chybná.

Kontrolní seznam pro vydání

Toto je seznam, který procházíme před každým vydáním Cold chain. Je krátký, protože většinu z něj za nás kontroluje platforma.

  1. Verze se shodují: manifest, pack.json a model znalostí, pokud se změnil.
  2. Každá brána je lokálně zelená, z čistého stavu, a u každého nového testu bylo prokázáno, že nejprve selhal.
  3. Stránka „Manifest a oprávnění“ neukazuje žádné rozšíření, nebo je rozšíření záměrné a recenzenti vědí proč.
  4. Každá migrace je nový číslovaný soubor, má vymezený rozsah a byla čistě aplikována na dočasnou databázi.
  5. scripts/ci/required-env uvádí každou proměnnou, kterou služba potřebuje, a nasazení každou z nich nastavuje.
  6. Plán vrácení zpět je zapsán ve změně, a to i pro jakoukoli změnu modelu.
  7. Tento týden jsou k dispozici dva recenzenti, kteří nejsou autory.

Poslední bod zní triviálně. Právě ten však zdržel více našich vydání než všechny brány dohromady.