PrijavaRezervirajte predstavitev

Poglavje 2.28

Izdajanje vaše razširitve

Kako vtičnik ali paket preide od uspešne izdelave do enot, ki ga izvajajo, in kako se ga znova umakne. Različice, pregled pred izdajo, kanali in namestitve, podpisovanje, odobritve sprememb, zapis o identiteti dostave, migracije, povrnitev v prejšnje stanje in upokojitev različice.

To stran je iz angleškega izvirnika prevedla UI. Če je karkoli nejasno, je referenca angleška stran. Preberite to stran v angleščini

18 min branja

Cold chain 0.4.0 je bila naša prva izdaja, ki je zahtevala več kot prejšnja. Dodala je pošiljanje pošte in en zunanji naslov za opozorila hladilnih zabojnikov. Gradnja je bila zelena, testi so uspeli na vseh treh sintetičnih poslovalnicah, pa je kljub temu dva dni ostala v razvojnem prostoru, medtem ko sta dva človeka prebrala, kaj zahteva, tretji pa je odobril naslov. Tako naj bi bilo izdajanje v Nexus: koda je lažji del, dokazila in odobritve pa so izdaja.

To poglavje obravnava vse med zeleno gradnjo in različico, ki teče za vse enote, ter poti nazaj. Sama pot napredovanja, od razvojnega prostora prek preizkusnega okolja in pilotne enote do vseh enot, je predstavljena v poglavju 2.24, Gradnja vertikale po meri od začetka do konca, zato njenih vrat tukaj ne bom ponavljal. Vse skupaj uokvirja eno pravilo. Uvajanje poteka izključno prek kanalov za izdaje namestitve. Za nujni popravek ni stranskih vrat in nihče ročno ne ureja delujoče slike.

Različice

Pri izdaji paketa se premikajo tri številke različic in splača se jih v mislih držati ločeno.

Kaj Kje se nahaja Primer Pravilo
Vtičnik version v nexus.manifest.json 0.4.0 Semantična različica; dovoljena je pripona predizdaje, kot je -rc.1
Paket version v pack.json 0.4.0 Premika se skupaj z lečami, besedami in gručami paketa
Model znanja Lastna različica modela 1.3 do 1.4 Premika se samo prek zahteve za spremembo grafa

Razvojna gradnja nosi pripono 0.4.0-dev, dokler ne doseže preizkusnega okolja. Kadar se vtičnik in paket izdajata skupaj, naj bosta njuni različici enaki; tako se pri vsakem pregledu izdaje izognete prepiru o tem, kateri številki pripadajo dokazila.

Dve drugi različici sta zaklenjeni in ne izbrani. Različica predloge paketa (domain-pack@1.6.0 za Cold chain) je določena ob ustvarjanju paketa in se spremeni samo s pregledano spremembo. SDK (komplet za razvoj programske opreme) je nameščen v točno določeni različici, nikoli v razponu, tako da ista gradnja tudi naslednji mesec da enak rezultat:

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

Tudi veščine Skills Engine imajo različice, vendar se obnašajo drugače. Vsaka objavljena različica je nespremenljiva, live, canary in shadow pa so oznake na različicah. Vrnitev nazaj premakne oznako, izvajanja, ki že potekajo, pa se dokončajo v različici, s katero so se začela.

Preden zaprosite za pregled: manifest

Stran Manifest in dovoljenja primerja, kar ta izdaja deklarira, z zadnjo izdajo: njene obsege, shrambe, odhodne naslove in profil peskovnika. Preberite jo, preden koga prosite za pregled, saj vam pove natanko, kaj bodo morali pregledovalci sprejeti.

Manifest in dovoljenja
Manifest in dovoljenja
Kaj Cold chain 0.4.0 deklarira v primerjavi z 0.3.2. Opazite dve vrstici, označeni kot razširitev, pošiljanje pošte in en zunanji naslov, ter ploščico, ki pravi, da izdaja ne bo napredovala iz razvojnega prostora, dokler ju ne sprejmeta dva pregledovalca.

Izdaja, ki zahteva več, kot je prej deklariral njen manifest, je zadržana tam, kjer je, z MANIFEST_SCOPE_WIDENED, dokler dva pregledovalca ne sprejmeta širšega manifesta. Zunanji naslov potrebuje tudi odobritev osebe, ki je pri stranki odgovorna za zunanje naslove; ta odobritev se izda za določen čas, naša je veljala 12 mesecev. Na voljo imate dve poti naprej: odstranite vrstici ali zaprosite za pregled. Stran ponuja oba gumba.

Vsaka vrstica na tej strani se uveljavlja med izvajanjem, ne samo pregleda. Vsak klic orodja se preveri glede na deklarirane obsege, zunanji naslov je blokiran, razen če je naveden, profil peskovnika pa ne dovoljuje nobenega drugega omrežja. Vtičnik, ki poskuša doseči nekaj, česar ni deklariral, je zavrnjen, edina rešitev pa je nova izdaja, ki to deklarira.

Pregled pred izdajo

Stran Pregled izdaje zbere dokazila za eno izdajo v eno tabelo, za pregledovalca, ki ni avtor.

Pregled izdaje
Pregled pred izdajo
Pogled drugega pregledovalca na Cold chain 0.4.0 s tabelo dokazil, razliko obsegov in komentarji. Opazite ploščico na desni: avtor ne more odobriti svoje lastne izdaje.
Dokazilo Kaj je pokazalo za 0.4.0
Testi 66 od 66, na treh sintetičnih poslovalnicah
Preverjanja kakovosti Dokumentacija in koda se ujemata
Pravilnik Vsaka leča samo zožuje; osebna polja so privzeto izklopljena
Podpisi Sliko in paket je podpisal cevovod
Razlika obsegov Doda pošiljanje pošte in en zunanji naslov z njegovo odobritvijo
Združljivost Različica platforme in različica osnovnega paketa, na katerih je bila testirana
Sprememba modela Preizkusni zagon zahteve za spremembo grafa: 1.284 povezav preimenovanih, nič odstranjenega

Pod tabelo so komentarji k spremembi in izvor: kateri cevovod jo je zgradil, iz katere spremembe, povzetek slike in predloga. Pregledovalci odobrijo s svojim ključem za dostop (passkey). Odobrita dva pregledovalca, ki nista avtor, nato pa cevovod premakne izdajo v preizkusno okolje. Avtor nikoli ne šteje kot pregledovalec, poskus pa je zavrnjen z NEEDS_SECOND_PERSON. Zahteva za pregled poteče po 3 dneh.

Na vprašanja pregledovalcev odgovarjajte v komentarjih, ne v oknu za klepet. Med našim pregledom je naša pooblaščenka za skladnost vprašala, zakaj je znesek zahtevka razvrščen kot poslovni podatek, drugi pregledovalec pa je zahteval načrt vrnitve za spremembo modela. Oba odgovora sta zdaj del zapisa izdaje, kamor bo pogledal naslednji pregledovalec.

Odobritve pravilnika o spremembah

Pregled izdaje zajema izdajo kot celoto. Blok changePolicy v manifestu gre dlje: določa, kateri razredi sprememb uvedljivih komponent vašega vtičnika potrebujejo odobritev in od koliko ljudi.

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

Trije razredi so website (spletna aplikacija), bff (zaledje za uporabniški vmesnik) in migration (migracija baze podatkov). Vsak razred, naveden v classes, mora imeti svoje število v approvals, od 1 do 10. Razred, ki ga izpustite, ni urejen, shema pa zahteva, da to zapišete kot odločitev, ne pa da do tega pride z opustitvijo. Za migracije zahtevamo dve odobritvi, ker je migracija edina sprememba, ki jo je težko razveljaviti.

Odobritve se štejejo po različnih osebah, predlagatelj pa nikoli ni med njimi. Pravila, ki to podpirajo, je vredno poznati, saj ima vsako svojo zavrnitev:

  • Odobritev osebe, ki je spremembo predlagala, je zavrnjena z TRUST_APPROVAL_SELF_APPROVAL.
  • Oseba, ki sploh ne sme izvajati sprememb tega razreda, je zavrnjena z CHANGE_CLASS_NOT_PERMITTED.
  • Kadar je katera koli potrditev v spremembi podpisana z identiteto agenta organizacije, je sklepčnost običajni minimum plus ena, glas samega agenta pa ne šteje.
  • Vsaka odobritev zabeleži razliko in vrh, ki ju je videla. Če se sprememba po zadnji odobritvi premakne, je njena združitev zavrnjena z HASH_MISMATCH, odobritve pa je treba za novo vsebino zbrati znova.

To tretje pravilo je pomembno, če gradite z orodjem za kodiranje z UI (umetno inteligenco), kot opisuje poglavje 2.26, Gradnja z orodji za kodiranje z UI. Delo, ki ga je napisal agent, potrebuje eno človeško odobritev več kot delo, ki ga je napisal človek. Načrtujte to.

Podpisovanje in preverjanje

Vsako sliko in paket podpiše cevovod, ki ju je zgradil, podpisana slika pa je eno od vrat v preizkusno okolje. Razvojni prostor že od začetka izvaja samo podpisane slike. V izdaji Enterprise skrbnik vsak imenski prostor nastavi tako, da nepodpisane slike bodisi beleži bodisi zavrača, in imenske prostore preklaplja na zavračanje enega za drugim, tako da produkcija na koncu izvaja samo slike, ki jih je cevovod zgradil in podpisal. Podpisovanje je del gradnje, ne nekaj, kar dodate pred izdajo.

Pravilo, ki se vleče skozi vse, je, da je neuspel podpis zavrnitev, nikoli opozorilo. Preverjanje, ki prejme SIG_INVALID, se ustavi. Ne preklopi na nepodpisano različico in ne nadaljuje z zapiskom v dnevniku, ker je opozorilo v dnevniku gradnje prehod za vse, ki ga niso prebrali.

Isto pravilo velja za vse, kar predate na nosilcih. Zapečateni sveženj za stranko brez omrežne povezave se preveri z vašim javnim ključem, preden se karkoli razpakira, ukaz pa prikazuje poglavje 2.25, Gradnja za vsako izdajo.

Identiteta dostave

Vtičnik se dostavlja prek več stvari, od katerih ima vsaka svoje ime: njegovi repozitoriji, podpisni ključ, imenski prostor za uvajanje, predpona registra, shema baze podatkov, nabor domen in pravilnik sprememb. Vsaka od njih je mesto, kjer bi lahko dva vtičnika trčila ali kjer bi en vtičnik lahko odstopil. Identiteta dostave je en podpisan zapis na vtičnik, ki vse to hrani, zato vsako preverjanje na poti izdaje prebere isti odgovor in ob neujemanju zavrne.

Svoj del prispevate prek manifesta in ničesar drugega: schema, db, domains, changePolicy in URL repozitorija. Platforma zapis dopolni z ostalim in ga podpiše. Nikoli sami ne poimenujete svojega imenskega prostora, predpone registra ali podpisnega ključa. Ti so vam dodeljeni, manifest, ki bi jih poskušal deklarirati, pa bi podajal trditev, ki bi ji morala preverjanja nato ne verjeti.

Podpisani zapis vsebuje enajst polj: slug vtičnika, organizacijo lastnico, organizacijo, ki ga gradi, njegove repozitorije, ime njegovega podpisnega ključa, imenski prostor za uvajanje, predpono registra, shemo baze podatkov, domene, pravilnik sprememb in kratek seznam starejših imen slik, ki jih je uporabljal, preden je obstajala njegova predpona registra. Ta zadnji seznam se lahko samo krči. Ker je podpisan, lahko nov podpis vnos odstrani, nič pa ga ne more tiho dodati. Podpis je Ed25519 nad standardno kanonično obliko JSON teh enajstih polj, zato se zapis, ki vsebuje "Tomás" ali "Sinéad", povsod preveri enako.

Kadar se izdaja ne ujema s svojim zapisom, velja prva zavrnitev:

Koda Kdaj HTTP
DELIVERY_IDENTITY_MISSING Za vtičnik ni zapisa 403
DELIVERY_PATH_REFUSED Potisk slike zunaj predpone registra, ki ni na podpisanem seznamu starejših imen 403
NAMESPACE_MISMATCH Uvedba, ki cilja na drug imenski prostor 403
IMAGE_NAME_COLLISION Ime slike, ki si ga že lasti drug vtičnik 409
CHANGE_CLASS_NOT_PERMITTED Razred sprememb, ki ga pravilnik ne ureja 403

IMAGE_NAME_COLLISION je tisti, ki ljudi preseneti. Izberite drugo ime in nikoli ne uporabite imena ponovno: skupno ime slike pomeni, da lahko napredovanje enega vtičnika premakne pode drugega vtičnika.

Potrjene in omejene migracije

Migracija se dostavi znotraj slike vašega vtičnika in se izvede pred zagonom nove različice, prek edinega izvajalnika migracij v SDK, nexus-migrate. Lastnega izvajalnika ne pišete. Preden se katera koli izdaja lahko premakne, isti izvajalnik vaše migracije uporabi datoteko za datoteko na začasni bazi podatkov, tako da migracija, ki ne uspe, ne uspe tam. Senčna gradnja predloge izvajalnik pokliče enkrat za vsako datoteko, po vrsti, in vsako datoteko zabeleži tako, kot jo bo produkcija.

Pravila izvajalnika so ista, kot jih preverjajo vrata, zapisana kot koda:

  1. Poveže se z vlogo migratorja vaše sheme in vsako datoteko izvede kot lastnik sheme. Vsaka druga prijava, predvsem superuporabnik, je zavrnjena. Datoteka, ki poskuša sama zamenjati vlogo, je zavrnjena, preden se karkoli izvede.
  2. Datoteka najemništva, oštevilčena z 0, se po uporabi nikoli ne ureja. Sprememba najemništva dobi lastno revizijsko datoteko, 000_tenancy_r<N>.sql, ki jo za vas napiše nexus-tenancy render --revision <N>.
  3. Običajno izvajalnik upravlja transakcijo vsake datoteke in v njej zavrne BEGIN ali COMMIT. Datoteka, ki sama upravlja svoje transakcije, deklarira, da se izvaja po stavkih, nato pa se mora ujemati vsak BEGIN, ki ga odpre.
  4. Vodi register, eno vrstico na datoteko, z SHA-256 datoteke in načinom izvedbe. Uporabljena datoteka se nikoli ne spreminja na mestu; sprememba je nova oštevilčena datoteka.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Omejeno na obseg pomeni, da vsaka nova tabela vsebuje organization_id, owner_user_id in business_unit_id, poleg tega označevalni stolpec is_demo, razen če gates/demo-exempt.json tabelo z utemeljitvijo izvzame, s primarnim ključem, ki se začne z organizacijo, in tujimi ključi, ki jo prenašajo, ter z vsiljeno varnostjo na ravni vrstic. Vrata migrations-are-scoped ta pravila preverijo v vsaki datoteki, migrations-commit-what-they-open pa preveri, da vsaka datoteka potrdi, kar odpre. Druga vrata obstajajo, ker se je migracija, ki se je tiho razveljavila, nekoč končala z 0, tabela, ki bi jo morala ustvariti, pa ni nikoli obstajala.

K vsaki izdaji spada še ena datoteka. scripts/ci/required-env izpiše spremenljivke okolja, ki jih vaša storitev potrebuje za zagon, kot polje JSON, vzeto iz vašega nalagalnika konfiguracije. Pot izdaje jo izvede in zavrne izdajo, katere uvedba ne nastavi vseh, tako da se manjkajoča spremenljivka odkrije pred izdajo, ne pa šele s podom, ki se ne zažene.

node scripts/ci/required-env

Izdajanje veščin

Obe vrsti veščin do ljudi prideta po različnih poteh, zato ju izdajajte različno.

Veščina manifesta, tipizirana vrstica v skills[] vašega vtičnika, se dostavi z vtičnikom in gre skozi isto napredovanje kot preostanek vtičnika. Uvajanje ob vsaki izdaji sinhronizira celoten nabor veščin z registrom. Če veščino izpustite iz nabora, je onemogočena, v izdaji Enterprise pa sinhronizacija z eno slabo veščino ne prevzame nobene, tako da še naprej teče prejšnja različica, ne pa polovica nove.

Veščina Skills Engine se objavi iz knjižnice. V paketu Enterprise mora veščino, ki doda orodje za pisanje, odobriti dva imenovana človeka s svojima ključema za dostop (passkey), predlagatelj pa ne more biti eden od njiju. Odobrena različica nato teče v senčnem načinu, nato kot kanarček za eno enoto za imenovanimi vrati, nato za vse, in se sama ustavi, če pogoj vrat ni izpolnjen. Če sta vaš vtičnik in veščina Skills Engine odvisna drug od drugega, najprej objavite veščino in počakajte, da doseže vse, preden izdaja vtičnika, ki jo kliče, zapusti pilot.

Kanali in namestitve

Ko izdaja prestane pilot in doseže vse enote, je ponujena na kanalu, vsaka enota pa izbere svoj kanal. Njen skrbnik privoli v vsak premik. Stran Kanali in namestitve prikazuje, katere enote poganjajo katero različico, s stopnjami napak le kot števili: vidite, kako se vaša razširitev obnaša, nikoli pa, kaj je kdo z njo počel.

Kanali in namestitve
Kanali in namestitve
Katere enote poganjajo katero različico carrier-sync, z odprto povrnitvijo za eno enoto. Bodite pozorni na to, kaj modalno okno navaja, da se spremeni, kaj ostane, in da potrebuje drugo osebo, lastnega skrbnika enote.

Naš vtičnik carrier-sync poganja tri različice hkrati, in to je običajno. Večina enot je na trenutni izdaji, ena enota ostaja na starejši različici na kanalu, ki se ohranja do navedenega datuma, kandidat za izdajo pa je na kanalu, ki ga še nihče ni izbral. Ne borite se proti temu; enota, ki potrebuje stabilnost zaradi revizije, je do nje upravičena.

Dnevniki in metrike vaše razširitve

Stran z dnevniki in metrikami za vaš paket je omejena na vaše lastne delovne obremenitve v enotah, v katere smete vpogledati. Filtrirate lahko po enoti in okolju, vidite pa števila, čase in stanja.

Dnevniki in metrike vašega paketa
Dnevniki in metrike vašega paketa
Lastni dnevniki in metrike Cold chain, filtrirani na pilot v Rotterdamu. Poglejte vrstice dnevnika: oseba, ki je prijavila odstopanje, je skrita, besedilo opombe k zahtevku pa se sploh nikoli ne beleži.

Osebna polja se nadomestijo, preden se vrstica zapiše, vsebina strank, kot so besedilo zahtevkov, pošta ali vsebina dokumentov, pa se nikoli ne zapiše v dnevnike. Dnevniki se hranijo 14 dni. Organizacijo določi prehod, nikoli vaša poizvedba, zato je poizvedba, ki navaja drugo organizacijo, zavrnjena z TENANT_BOUNDARY. Pomočnik v vrstici lahko skupaj z vami bere iste dnevnike, in samo te: ko sem ga vprašal, zakaj so zapisi o odstopanjih nekega jutra prišli pozno, je 18 minut ponovnih poskusov izsledil do podvojenih odčitkov iz napajanja enega pomola.

Povrnitev v prejšnje stanje

Obstajata dve vrsti povrnitve in obe sta pregledani spremembi, ne stikali.

Povrnitev okolja uporabi prejšnjo različico. Vsako okolje jo hrani 30 dni. Povrnitev se pripravi kot sprememba izdaje, prikaže predogled tega, kar bo naredila, in potrebuje drugo osebo; ko je odobrena, cevovod povrne v približno minuti. Vsaka povrnitev se časovno meri, prav tako vsaka vaja, zato jo vadite, preden jo potrebujete. Povrnitev ene enote uporablja stran Kanali in namestitve. Modalno okno za povrnitev navaja, kaj se spremeni (ta enota znova poganja starejšo različico, njena stopnja napak pa se eno uro spremlja), kaj ostane (druge enote ter nastavitve in zapisi enote), razlog in kdo je druga oseba: skrbnik te enote.

Nastavitve in zapisi se ob povrnitvi ohranijo, zato vsako izdajo načrtujte ob predpostavki, da se lahko prejšnja različica znova zažene na podatkih, ki jih je zapisala novejša. To je praktični razlog, da migracije znotraj izdaje, ki bi jo morda povrnili, ostanejo dodajalne, in razlog, da zahtevamo, da vsako odobrita dve osebi. Sprememba modela je enaka: pregledovalec lahko, in bi moral, pred odobritvijo zahtevati načrt povrnitve za zahtevo za spremembo grafa.

Veščine se povrnejo bolj nežno. Premik oznake live nazaj na prejšnjo različico je en korak, izvajanja, ki že potekajo, pa se dokončajo na različici, s katero so se začela.

Upokojitev različice

Izdaja se, ko je enkrat narejena, nikoli ne ureja. Različica, ki se ne bi smela več uporabljati, se umakne, popravek pa se izda kot nova številka različice. Lastni kanali izdaj SDK sledijo isti navadi: slaba različica SDK se odstrani, nikoli pa nadomesti z drugačno vsebino pod isto številko. Posnemajte to, ker številka različice, ki lahko pomeni dve različni gradnji, naredi vsak dokaz o njej brez vrednosti.

Umik vtičnika ali paketa ustavi nove namestitve. Enote obdržijo različico, ki jo poganjajo, dokler se ne premaknejo, zato je umik signal in rok, ne izklopno stikalo. Skrbnikom enot sporočite, na katero različico naj preidejo in do kdaj.

Upokojitev veščine sledi isti zamisli z enim dodatnim korakom. Skills Engine po izvedbi primerov nadomestne veščine premakne vse preostale klicatelje nanjo, ustavi nova izvajanja ter ohrani različice, primere in zapečatene zapise izvajanj, tako da je veščino mogoče vrniti, če se nadomestna izkaže za napačno.

Kontrolni seznam za izdajo

To je seznam, ki ga preberemo pred vsako izdajo Cold chain. Kratek je, ker platforma večino preveri namesto nas.

  1. Različice se ujemajo: manifest, pack.json in model znanja, če se je spremenil.
  2. Vsaka vrata so lokalno zelena, iz čistega stanja, in za vsak nov test je bilo pokazano, da najprej spodleti.
  3. Stran Manifest in dovoljenja ne kaže razširitve ali pa je razširitev tisto, kar smo nameravali, in pregledovalci vedo, zakaj.
  4. Vsaka migracija je nova oštevilčena datoteka z omejenim obsegom, čisto uveljavljena na začasni podatkovni bazi.
  5. scripts/ci/required-env navaja vsako spremenljivko, ki jo storitev potrebuje, in uvedba nastavi vsako od njih.
  6. Načrt povrnitve je zapisan v spremembi, tudi za vsako spremembo modela.
  7. Ta teden sta na voljo dva pregledovalca, ki nista avtorja.

Zadnja točka se zdi nepomembna. Prav ta je zamaknila več naših izdaj kot vsa vrata skupaj.