AutentificareProgramați o prezentare

Capitolul 2.28

Lansarea extensiei dumneavoastră

Cum ajunge un plugin sau un pachet de la o compilare validată la unitățile care îl rulează și cum este retras din nou. Versiuni, revizuirea lansării, canale și instalări, semnare, aprobări de modificare, înregistrarea identității livrării, migrări, revenire la versiunea anterioară (rollback) și retragerea unei versiuni.

Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

18 minute de lectură

Cold chain 0.4.0 a fost prima noastră versiune care a cerut mai mult decât cea dinaintea ei. A adăugat trimiterea de e-mailuri și o adresă externă, pentru alertele privind containerele frigorifice. Build-ul era verde, testele treceau pe toate cele trei ramuri sintetice și, totuși, versiunea a stat două zile în spațiul de dezvoltare, în timp ce două persoane citeau ce cerea, iar o a treia aproba adresa. Așa trebuie să se simtă lansarea unei versiuni pe Nexus: codul este partea ușoară, iar dovezile și aprobările sunt lansarea propriu-zisă.

Acest capitol acoperă tot ce se întâmplă între un build verde și o versiune care rulează pentru toate unitățile, precum și căile de revenire. Traseul de promovare în sine, de la spațiul de dezvoltare la staging, la o unitate pilot și la toate unitățile, este prezentat în capitolul 2.24, Construirea unei verticale personalizate de la un capăt la altul, și nu voi repeta aici etapele sale de control. O singură regulă încadrează totul. Implementarea se face exclusiv prin canalele de lansare ale instalării. Nu există nicio ușă laterală pentru o remediere urgentă și nimeni nu modifică manual o imagine care rulează.

Versiuni

Într-o lansare de pachet se modifică trei numere de versiune și merită să le păstrați distincte în minte.

Ce Unde se află Exemplu Regulă
Pluginul version în nexus.manifest.json 0.4.0 Versiune semantică; este permis un sufix de pre-lansare, cum ar fi -rc.1
Pachetul version în pack.json 0.4.0 Se modifică odată cu lentilele, termenii și clusterele pachetului
Modelul de cunoștințe Versiunea proprie a modelului 1.3 la 1.4 Se modifică doar printr-o cerere de modificare a grafului

Un build de dezvoltare poartă un sufix, 0.4.0-dev, până când ajunge în staging. Păstrați egale versiunile pluginului și pachetului atunci când sunt livrate împreună; astfel evitați, la fiecare revizuire a versiunii, discuția despre numărul căruia îi aparțin dovezile.

Alte două versiuni sunt fixate, nu alese. Versiunea șablonului pachetului (domain-pack@1.6.0 pentru Cold chain) este stabilită la crearea pachetului și se modifică doar printr-o modificare revizuită. SDK-ul (kitul de dezvoltare software) este instalat la o versiune exactă, niciodată la un interval, astfel încât același build să dea același rezultat și luna viitoare:

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

Și abilitățile din Skills Engine au versiuni, dar acestea se comportă diferit. Fiecare versiune publicată este fixă, iar live, canary și shadow sunt etichete aplicate versiunilor. Revenirea mută o etichetă, iar rulările deja în desfășurare se încheie pe versiunea cu care au început.

Înainte de a solicita revizuirea: manifestul

Pagina Manifest și permisiuni compară ceea ce declară această versiune cu ultima versiune: domeniile de acces, depozitele de date, adresele externe și profilul sandbox. Citiți-o înainte de a cere cuiva o revizuire, deoarece vă arată exact ce li se va cere revizorilor să accepte.

Manifest și permisiuni
Manifest și permisiuni
Ce declară Cold chain 0.4.0 față de 0.3.2. Observați cele două linii marcate ca extinderi, trimiterea de e-mailuri și o adresă externă, precum și plăcuța care arată că versiunea nu va trece dincolo de spațiul de dezvoltare până când doi revizori nu le acceptă.

O versiune care cere mai mult decât declara anterior manifestul său este reținută acolo unde se află, cu MANIFEST_SCOPE_WIDENED, până când doi revizori acceptă manifestul extins. O adresă externă necesită și aprobarea persoanei care gestionează adresele externe la client; această aprobare se acordă pentru o perioadă fixă, iar a noastră a fost pentru 12 luni. Aveți două căi de urmat: eliminați liniile sau solicitați o revizuire. Pagina oferă ambele butoane.

Fiecare linie de pe acea pagină este aplicată în timpul rulării, nu doar revizuită. Fiecare apel de instrument este verificat în raport cu domeniile de acces declarate, o adresă externă este blocată dacă nu este listată, iar profilul sandbox nu permite nicio altă rețea. Un plugin care încearcă să acceseze ceva ce nu a declarat este refuzat, iar singura soluție este o nouă versiune care să declare acel lucru.

Revizuirea lansării

Pagina Revizuirea versiunii reunește dovezile pentru o versiune într-un singur tabel, pentru un revizor care nu este autorul.

Revizuirea versiunii
Revizuirea lansării
Vizualizarea unui al doilea revizor pentru Cold chain 0.4.0, cu tabelul de dovezi, diferențele de domenii de acces și comentariile. Observați plăcuța din dreapta: autorul nu își poate aproba propria versiune.
Dovezi Ce a arătat pentru 0.4.0
Teste 66 din 66, pe trei ramuri sintetice
Verificări de calitate Documentația și codul concordă
Politică Fiecare lentilă doar restrânge; câmpurile personale sunt dezactivate implicit
Semnături Imagine și pachet semnate de pipeline
Diferențe de domenii de acces Adaugă trimiterea de e-mailuri și o adresă externă, cu aprobarea aferentă
Compatibilitate Versiunea platformei și versiunea pachetului de bază pe care a fost testată
Modificarea modelului Rularea de probă a cererii de modificare a grafului: 1.284 de legături redenumite, nimic eliminat

Sub tabel se află comentariile la modificare și proveniența: ce pipeline a construit-o, din ce modificare, digestul imaginii și șablonul. Revizorii aprobă cu passkey-ul lor. Doi revizori care nu sunt autorul aprobă, iar pipeline-ul mută apoi versiunea în staging. Autorul nu este niciodată considerat revizor, iar o încercare este refuzată cu NEEDS_SECOND_PERSON. O cerere de revizuire expiră după 3 zile.

Răspundeți la întrebările revizorilor în comentarii, nu într-o fereastră de chat. În timpul revizuirii noastre, responsabilul nostru de conformitate a întrebat de ce valoarea despăgubirii era clasificată drept comercială, iar al doilea revizor a cerut planul de revenire pentru modificarea modelului. Ambele răspunsuri fac acum parte din registrul versiunii, acolo unde va căuta următorul revizor.

Aprobări privind politica de modificare

Revizuirea versiunii acoperă versiunea în ansamblu. Blocul changePolicy din manifest merge mai departe: precizează ce clase de modificări ale componentelor implementabile ale pluginului dumneavoastră necesită aprobare și de la câte persoane.

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

Cele trei clase sunt website (aplicația web), bff (backend-ul pentru frontend) și migration (o migrare a bazei de date). Fiecare clasă numită în classes trebuie să aibă propriul număr în approvals, de la 1 la 10. O clasă pe care o omiteți nu este guvernată, iar schema vă obligă să scrieți acest lucru ca pe o alegere, nu să ajungeți la el prin omisiune. Cerem două aprobări pentru migrări, deoarece o migrare este singura modificare greu de anulat.

Aprobările se numără în persoane distincte, iar inițiatorul nu este niciodată una dintre ele. Merită să cunoașteți regulile care susțin acest lucru, deoarece fiecare are un refuz asociat:

  • O aprobare din partea persoanei care a propus modificarea este refuzată cu TRUST_APPROVAL_SELF_APPROVAL.
  • O persoană care nu are deloc dreptul de a face o modificare din acea clasă este refuzată cu CHANGE_CLASS_NOT_PERMITTED.
  • Atunci când orice commit din modificare este semnat de identitatea de agent a organizației, cvorumul este minimul obișnuit plus unu, iar votul propriu al agentului nu se numără.
  • Fiecare aprobare înregistrează diferențele și head-ul pe care le-a văzut. Dacă modificarea se schimbă după ultima aprobare, îmbinarea ei este refuzată cu HASH_MISMATCH, iar aprobările trebuie colectate din nou pentru noul conținut.

A treia regulă contează dacă dezvoltați cu un instrument de programare bazat pe IA (inteligență artificială), așa cum descrie capitolul 2.26, Dezvoltarea cu instrumente de programare bazate pe IA. Munca scrisă de un agent necesită o aprobare umană în plus față de munca scrisă de o persoană. Planificați în consecință.

Semnare și verificare

Fiecare imagine și fiecare pachet sunt semnate de pipeline-ul care le-a construit, iar o imagine semnată este una dintre etapele de control pentru intrarea în staging. Un spațiu de dezvoltare rulează doar imagini semnate încă de la început. În Enterprise, un administrator setează fiecare namespace fie să înregistreze imaginile nesemnate, fie să le refuze, și trece namespace-urile pe refuz unul câte unul, astfel încât producția ajunge să ruleze doar imagini construite și semnate de pipeline. Semnarea face parte din build, nu este ceva ce adăugați înainte de o lansare.

Regula care străbate totul este că o semnătură care eșuează înseamnă un refuz, niciodată un avertisment. O verificare care primește SIG_INVALID se oprește. Nu revine la versiunea nesemnată și nu continuă cu o notă într-un jurnal, deoarece un avertisment într-un jurnal de build este o aprobare pentru toți cei care nu l-au citit.

Aceeași regulă se aplică tuturor celor pe care le predați pe suport fizic. Un pachet sigilat pentru un client izolat de rețea (air-gapped) este verificat cu cheia dumneavoastră publică înainte de a se despacheta ceva, iar capitolul 2.25, Dezvoltarea pentru fiecare ediție, prezintă comanda.

Identitatea livrării

Un plugin este livrat prin mai multe elemente, fiecare cu un nume: depozitele sale, o cheie de semnare, un namespace de implementare, un prefix de registru, o schemă de bază de date, un set de domenii și o politică de modificare. Oricare dintre ele este un loc în care două pluginuri ar putea intra în conflict sau în care un plugin ar putea devia. Identitatea de livrare este o singură înregistrare semnată pe plugin, care le conține pe toate, astfel încât fiecare verificare de pe traseul de lansare citește același răspuns și refuză în caz de nepotrivire.

Contribuiți cu partea dumneavoastră prin manifest și prin nimic altceva: schema, db, domains, changePolicy și URL-ul depozitului. Platforma completează înregistrarea cu restul și o semnează. Nu vă denumiți niciodată singur namespace-ul, prefixul de registru sau cheia de semnare. Acestea vă sunt atribuite, iar un manifest care ar încerca să le declare ar face o afirmație pe care verificările ar trebui apoi să o respingă.

Înregistrarea semnată conține unsprezece câmpuri: slug-ul pluginului, organizația proprietară, organizația care îl construiește, depozitele sale, numele cheii sale de semnare, namespace-ul de implementare, prefixul de registru, schema bazei de date, domeniile, politica de modificare și o listă scurtă de nume de imagini mai vechi pe care le-a folosit înainte să existe prefixul său de registru. Această ultimă listă poate doar să se micșoreze. Deoarece este semnată, o nouă semnătură poate elimina o intrare, dar nimic nu poate adăuga una pe tăcute. Semnătura este Ed25519 aplicată formei JSON canonice standard a acestor unsprezece câmpuri, astfel încât o înregistrare care conține „Tomás” sau „Sinéad” se verifică la fel peste tot.

Atunci când o versiune nu corespunde înregistrării sale, primul refuz are câștig de cauză:

Cod Când HTTP
DELIVERY_IDENTITY_MISSING Nu există nicio înregistrare pentru plugin 403
DELIVERY_PATH_REFUSED O publicare de imagine în afara prefixului de registru, care nu se află pe lista semnată de nume mai vechi 403
NAMESPACE_MISMATCH O implementare care vizează un alt namespace 403
IMAGE_NAME_COLLISION Un nume de imagine revendicat deja de un alt plugin 409
CHANGE_CLASS_NOT_PERMITTED O clasă de modificări pe care politica nu o guvernează 403

IMAGE_NAME_COLLISION este cel care îi surprinde pe oameni. Alegeți un alt nume și nu reutilizați niciodată unul: un nume de imagine comun înseamnă că promovarea unui plugin poate muta podurile altui plugin.

Migrări, aplicate și cu domeniu definit

O migrare este livrată în interiorul imaginii pluginului dumneavoastră și rulează înainte de pornirea noii versiuni, prin singurul executor de migrări al SDK-ului, nexus-migrate. Nu vă scrieți propriul aplicator. Înainte ca orice versiune să poată avansa, același executor vă aplică migrările fișier cu fișier pe o bază de date temporară, astfel încât o migrare care eșuează eșuează acolo. Build-ul shadow al șablonului apelează executorul o dată pentru fiecare fișier, în ordine, și înregistrează fiecare fișier așa cum o va face producția.

Regulile executorului sunt cele verificate de etapele de control, scrise sub formă de cod:

  1. Se conectează cu rolul de migrator al schemei dumneavoastră și rulează fiecare fișier ca proprietar al schemei. Orice altă autentificare, în primul rând cea a unui superutilizator, este refuzată. Un fișier care încearcă să schimbe singur rolul este refuzat înainte să ruleze ceva.
  2. Fișierul de tenancy, numerotat 0, nu este niciodată editat după ce a fost aplicat. O modificare a tenancy-ului primește propriul fișier de revizie, 000_tenancy_r<N>.sql, pe care nexus-tenancy render --revision <N> îl scrie pentru dumneavoastră.
  3. În mod normal, executorul deține tranzacția fiecărui fișier și refuză un BEGIN sau un COMMIT în interiorul acesteia. Un fișier care își gestionează propriile tranzacții declară că rulează per instrucțiune, iar apoi fiecare BEGIN pe care îl deschide trebuie să aibă un corespondent.
  4. Păstrează un registru, cu un rând pentru fiecare fișier, conținând SHA-256 al fișierului și modul în care a rulat. Un fișier aplicat nu este niciodată modificat pe loc; o modificare înseamnă un nou fișier numerotat.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Delimitat înseamnă că fiecare tabel nou conține organization_id, owner_user_id și business_unit_id, plus coloana marcator is_demo, cu excepția cazului în care gates/demo-exempt.json exceptează tabelul cu o justificare, are o cheie primară care începe cu organizația și chei străine care o conțin, iar securitatea la nivel de rând este impusă. Etapa de control migrations-are-scoped verifică aceste reguli în fiecare fișier, iar migrations-commit-what-they-open verifică faptul că fiecare fișier confirmă (commit) ceea ce deschide. A doua etapă de control există deoarece o migrare care a fost anulată în tăcere s-a încheiat cândva cu codul 0, iar tabelul pe care ar fi trebuit să îl creeze nu a existat niciodată.

Fiecărei versiuni îi mai aparține un fișier. scripts/ci/required-env afișează variabilele de mediu de care serviciul dumneavoastră are nevoie pentru a porni, sub forma unui tablou JSON preluat din încărcătorul de configurație. Traseul de lansare îl rulează și refuză o versiune a cărei implementare nu setează fiecare dintre ele, astfel încât o variabilă lipsă este detectată înainte de lansare, nu de un pod care nu pornește.

node scripts/ci/required-env

Lansarea competențelor

Cele două tipuri de abilități ajung la utilizatori pe căi diferite, așa că lansați-le diferit.

O abilitate de manifest, un rând tipizat din skills[] al pluginului dumneavoastră, este livrată împreună cu pluginul și trece prin aceeași promovare ca restul acestuia. Onboarding-ul sincronizează întregul set de abilități cu registrul la fiecare lansare. Dacă omiteți o abilitate din set, aceasta este dezactivată, iar în Enterprise o sincronizare cu o singură abilitate defectă nu preia niciuna dintre ele, astfel încât versiunea anterioară continuă să ruleze, în locul unei jumătăți din cea nouă.

O abilitate Skills Engine se publică din bibliotecă. În Enterprise, una care adaugă un instrument de scriere așteaptă ca două persoane desemnate să o aprobe cu cheile lor de acces (passkeys), iar cel care o propune nu poate fi una dintre ele. O versiune aprobată rulează apoi în modul umbră, apoi în canary pentru o unitate, sub praguri de control desemnate, apoi pentru toată lumea, și se oprește singură dacă un prag nu este îndeplinit. Dacă pluginul dumneavoastră și o abilitate Skills Engine depind unul de celălalt, publicați mai întâi abilitatea și lăsați-o să ajungă la toată lumea înainte ca versiunea pluginului care o apelează să iasă din etapa pilot.

Canale și instalări

După ce o versiune a trecut de etapa pilot și a ajuns la toate unitățile, aceasta este oferită pe un canal, iar fiecare unitate își alege canalul. Administratorul unității aprobă fiecare trecere. Pagina Canale și instalări arată ce versiune rulează fiecare unitate, cu ratele de eroare exprimate doar ca număr: vedeți cum se comportă extensia dumneavoastră, niciodată ce a făcut cineva cu ea.

Canale și instalări
Canale și instalări
Ce versiune de carrier-sync rulează fiecare unitate, cu o revenire deschisă pentru o unitate. Observați ce spune fereastra modală că se schimbă, ce rămâne și faptul că necesită o a doua persoană, administratorul propriu al unității.

Pluginul nostru carrier-sync rulează trei versiuni simultan, iar acest lucru este normal. Majoritatea unităților folosesc versiunea curentă, o unitate rămâne pe o versiune mai veche, pe un canal menținut până la o dată anunțată, iar o versiune candidată se află pe un canal pe care încă nu l-a ales nimeni. Nu vă împotriviți; o unitate care are nevoie de stabilitate pentru un audit are dreptul la ea.

Jurnalele și indicatorii extensiei dumneavoastră

Pagina de jurnale și metrici a pachetului dumneavoastră este limitată la propriile sarcini de lucru, în unitățile în care aveți dreptul să priviți. Puteți filtra după unitate și mediu și vedeți numărători, durate și stări.

Jurnalele și metricile pachetului dumneavoastră
Jurnalele și metricile pachetului dumneavoastră
Jurnalele și metricile proprii ale Cold chain, filtrate pentru pilotul din Rotterdam. Priviți liniile de jurnal: persoana care a raportat o abatere este ascunsă, iar textul notei de reclamație nu este niciodată înregistrat în jurnal.

Câmpurile personale sunt înlocuite înainte ca o linie să fie scrisă, iar conținutul clienților, cum ar fi textul reclamațiilor, e-mailurile sau conținutul documentelor, nu este niciodată scris în jurnale. Jurnalele sunt păstrate 14 zile. Organizația este stabilită de gateway, niciodată de interogarea dumneavoastră, așa că o interogare care numește o altă organizație este refuzată cu TENANT_BOUNDARY. Asistentul din bara laterală poate citi aceleași jurnale împreună cu dumneavoastră, și doar pe acestea: când l-am întrebat de ce înregistrările de abateri au sosit cu întârziere într-o dimineață, a identificat 18 minute de reîncercări cauzate de citiri duplicate provenite de la alimentarea electrică a unui cheu.

Revenirea la o versiune anterioară

Există două tipuri de revenire, iar ambele sunt modificări revizuite, nu simple comutatoare.

Revenirea unui mediu folosește versiunea anterioară. Fiecare mediu o păstrează timp de 30 de zile. Revenirea este pregătită ca modificare a versiunii, previzualizează ce va face și necesită o a doua persoană; odată aprobată, pipeline-ul revine în aproximativ un minut. Fiecare revenire este cronometrată, la fel și fiecare exercițiu, așa că exersați una înainte să aveți nevoie de ea. Revenirea unei singure unități folosește pagina Canale și instalări. Fereastra modală de revenire arată ce se schimbă (unitatea respectivă rulează din nou versiunea mai veche, iar rata sa de eroare este monitorizată timp de o oră), ce rămâne (celelalte unități, precum și setările și înregistrările unității), motivul și cine este a doua persoană: administratorul unității respective.

Setările și înregistrările se păstrează la o revenire, așa că planificați fiecare versiune pornind de la premisa că versiunea anterioară ar putea rula din nou pe datele scrise de cea nouă. Acesta este motivul practic pentru care migrările trebuie să fie doar aditive într-o versiune la care s-ar putea reveni și motivul pentru care cerem ca fiecare dintre ele să fie aprobată de două persoane. O modificare de model este la fel: un evaluator poate, și ar trebui, să ceară planul de revenire al unei cereri de modificare a grafului înainte de a o aproba.

Abilitățile revin mai blând. Mutarea etichetei live înapoi la o versiune anterioară este un singur pas, iar rulările aflate deja în desfășurare se încheie pe versiunea cu care au început.

Retragerea unei versiuni

O versiune, odată publicată, nu este niciodată modificată. O versiune care nu mai trebuie folosită este retrasă, iar o corecție se livrează sub un nou număr de versiune. Canalele de lansare ale SDK-ului urmează același obicei: o versiune defectă a SDK-ului este retrasă, niciodată înlocuită cu alt conținut sub același număr. Preluați această practică, deoarece un număr de versiune care poate însemna două build-uri diferite face lipsită de valoare orice dovadă despre el.

Retragerea unui plugin sau a unui pachet oprește instalările noi. Unitățile păstrează versiunea pe care o rulează până când trec la alta, așa că retragerea este un semnal și un termen-limită, nu un întrerupător. Spuneți administratorilor unităților la ce versiune să treacă și până când.

Scoaterea din uz a unei abilități urmează aceeași idee, cu un pas în plus. Skills Engine mută toți apelanții rămași către o abilitate de înlocuire după ce rulează cazurile acesteia, oprește rulările noi și păstrează versiunile, cazurile și înregistrările sigilate ale rulărilor, astfel încât abilitatea să poată fi readusă dacă înlocuirea se dovedește greșită.

O listă de verificare pentru lansare

Aceasta este lista pe care o citim înainte de fiecare versiune Cold chain. Este scurtă pentru că platforma verifică majoritatea punctelor în locul nostru.

  1. Versiunile concordă: manifestul, pack.json și modelul de cunoștințe, dacă acesta s-a modificat.
  2. Fiecare prag de control este verde local, pornind de la zero, iar fiecare test nou a fost demonstrat mai întâi că eșuează.
  3. Pagina Manifest și permisiuni nu arată nicio extindere, sau extinderea este cea intenționată, iar evaluatorii știu de ce.
  4. Fiecare migrare este un fișier nou, numerotat, cu domeniu delimitat, și se aplică fără erori pe o bază de date temporară.
  5. scripts/ci/required-env enumeră fiecare variabilă de care are nevoie serviciul, iar implementarea o setează pe fiecare.
  6. Planul de revenire este scris în modificare, inclusiv pentru orice modificare de model.
  7. Doi evaluatori care nu sunt autorul sunt disponibili săptămâna aceasta.

Ultimul punct pare banal. Este cel care ne-a întârziat mai multe versiuni decât toate pragurile de control la un loc.