Versione 1.0.0-alpha.1ultima
Capitolo 2.28
Rilasciare l'estensione
Come un plugin o un pacchetto passa da una build superata alle unità che lo eseguono, e come viene eventualmente ritirato. Versioni, revisione del rilascio, canali e installazioni, firma, approvazioni delle modifiche, record dell'identità di distribuzione, migrazioni, rollback e ritiro di una versione.
Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

Cold chain 0.4.0 è stata la nostra prima release a richiedere più di quella precedente. Aggiungeva l'invio di posta e un indirizzo esterno, per gli avvisi dei reefer. La build era verde, i test erano superati su tutti e tre i rami sintetici, eppure è rimasta nel dev space per due giorni mentre due persone leggevano ciò che richiedeva e una terza approvava l'indirizzo. È così che dovrebbe essere un rilascio su Nexus: il codice è la parte facile, e le evidenze e le approvazioni sono la release.
Questo capitolo tratta tutto ciò che sta tra una build verde e una versione in esecuzione per ogni unità, e i modi per tornare indietro. Il percorso di promozione in sé, dal dev space allo staging a un'unità pilota a tutte le unità, è introdotto nel capitolo 2.24, Costruire un verticale personalizzato end to end, e qui non ne ripeterò i controlli. Una regola fa da cornice a tutto. Il deploy avviene solo tramite i canali di rilascio dell'installazione. Non esiste una porta laterale per una correzione urgente, e nessuno modifica a mano un'immagine in esecuzione.
Versioni
In una release di un pack si muovono tre numeri di versione, e conviene tenerli ben distinti.
| Cosa | Dove si trova | Esempio | Regola |
|---|---|---|---|
| Il plugin | version in nexus.manifest.json |
0.4.0 |
Versione semantica; è consentito un suffisso di pre-release come -rc.1 |
| Il pack | version in pack.json |
0.4.0 |
Si muove con le lenti, i termini e i cluster del pack |
| Il modello di conoscenza | La versione propria del modello | Da 1.3 a 1.4 |
Si muove solo tramite una richiesta di modifica del grafo |
Una build di sviluppo porta un suffisso, 0.4.0-dev, finché non raggiunge lo staging. Mantenga uguali le versioni del plugin e del pack quando vengono distribuiti insieme; si evita così, in ogni revisione della release, una discussione su a quale numero appartengano le evidenze.
Altre due versioni sono fissate anziché scelte. La versione del template del pack (domain-pack@1.6.0 per Cold chain) viene fissata quando il pack viene creato e cambia solo come modifica revisionata. L'SDK (software development kit) è installato a una versione esatta, mai un intervallo, così la stessa build dà lo stesso risultato il mese successivo:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Anche le skill dello Skills Engine hanno versioni, e si comportano diversamente. Ogni versione pubblicata è fissa, e live, canary e shadow sono etichette sulle versioni. Tornare indietro sposta un'etichetta, e le esecuzioni già in corso terminano sulla versione con cui sono iniziate.
Prima di richiedere la revisione: il manifest
La pagina Manifest e permessi confronta ciò che questa release dichiara con l'ultima release: i suoi scope, i suoi archivi, i suoi indirizzi in uscita e il suo profilo sandbox. La legga prima di chiedere a qualcuno di revisionare, perché le indica esattamente cosa verrà chiesto di accettare ai revisori.
Una release che richiede più di quanto il suo manifest dichiarasse in precedenza viene trattenuta dove si trova, con MANIFEST_SCOPE_WIDENED, finché due revisori non accettano il manifest ampliato. Un indirizzo esterno richiede inoltre l'approvazione di chi, presso il cliente, è responsabile degli indirizzi esterni; tale approvazione è concessa per un periodo fisso, e la nostra era di 12 mesi. Ha due modi per procedere: rimuovere le righe oppure richiedere la revisione. La pagina offre entrambi i pulsanti.
Ogni riga di quella pagina viene applicata in fase di esecuzione, non solo revisionata. Ogni chiamata a uno strumento viene verificata rispetto agli scope dichiarati, un indirizzo esterno viene bloccato se non è elencato, e il profilo sandbox non consente nessun'altra rete. Un plugin che tenta di raggiungere qualcosa che non ha dichiarato viene rifiutato, e l'unica soluzione è una nuova release che lo dichiari.
Revisione del rilascio
La pagina Revisione della release riunisce le evidenze di una release in un'unica tabella, per un revisore che non ne sia l'autore.
| Evidenza | Cosa ha mostrato per la 0.4.0 |
|---|---|
| Test | 66 su 66, su tre rami sintetici |
| Controlli di qualità | La documentazione e il codice concordano |
| Criterio | Ogni lente restringe soltanto; campi personali disattivati per impostazione predefinita |
| Firme | Immagine e pacchetto firmati dalla pipeline |
| Diff degli scope | Aggiunge l'invio di posta e un indirizzo esterno, con la relativa approvazione |
| Compatibilità | La versione della piattaforma e la versione del pack di base su cui è stata testata |
| Modifica del modello | La simulazione della richiesta di modifica del grafo: 1.284 collegamenti rinominati, nulla rimosso |
Sotto la tabella si trovano i commenti sulla modifica e la provenienza: quale pipeline l'ha costruita, da quale modifica, il digest dell'immagine e il template. I revisori approvano con la propria passkey. Due revisori diversi dall'autore approvano, e la pipeline sposta quindi la release in staging. L'autore non conta mai come revisore, e un tentativo viene rifiutato con NEEDS_SECOND_PERSON. Una richiesta di revisione scade dopo 3 giorni.
Risponda alle domande dei revisori nei commenti, non in una finestra di chat. Durante la nostra revisione, il nostro responsabile della conformità ha chiesto perché l'importo del sinistro fosse classificato come commerciale, e il secondo revisore ha chiesto il piano di rollback per la modifica del modello. Entrambe le risposte fanno ora parte del registro della release, che è dove guarderà il prossimo revisore.
Approvazioni della policy di modifica
La revisione della release copre la release nel suo insieme. Il blocco changePolicy nel manifest va oltre: indica quali classi di modifica ai deployable del plugin richiedono approvazione, e da quante persone.
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Le tre classi sono website (la web app), bff (il backend for frontend) e migration (una migrazione del database). Ogni classe indicata in classes deve avere un proprio conteggio in approvals, da 1 a 10. Una classe che viene omessa non è governata, e lo schema La obbliga a scriverlo come una scelta anziché arrivarci per omissione. Chiediamo due approvazioni per le migrazioni perché una migrazione è l'unica modifica difficile da annullare.
Le approvazioni sono conteggiate in persone distinte, e chi propone non è mai una di esse. Vale la pena conoscere le regole che lo garantiscono, perché ciascuna ha un rifiuto:
- Un'approvazione da parte della persona che ha proposto la modifica viene rifiutata con
TRUST_APPROVAL_SELF_APPROVAL. - Una persona che non può affatto apportare una modifica di quella classe viene rifiutata con
CHANGE_CLASS_NOT_PERMITTED. - Quando un qualsiasi commit della modifica è firmato dall'identità agente dell'organizzazione, il quorum è il minimo consueto più uno, e il voto dell'agente stesso non conta.
- Ogni approvazione registra il diff e l'head che ha visto. Se la modifica cambia dopo l'ultima approvazione, il merge viene rifiutato con
HASH_MISMATCH, e le approvazioni devono essere raccolte di nuovo per il nuovo contenuto.
Questa terza regola è importante se sviluppa con uno strumento di programmazione basato sull'IA (intelligenza artificiale), come descritto nel capitolo 2.26, Sviluppare con strumenti di programmazione basati sull'IA. Il lavoro scritto da un agente richiede un'approvazione umana in più rispetto al lavoro scritto da una persona. Ne tenga conto nella pianificazione.
Firma e verifica
Ogni immagine e pacchetto è firmato dalla pipeline che lo ha costruito, e un'immagine firmata è uno dei controlli per l'accesso allo staging. Un dev space esegue solo immagini firmate fin dall'inizio. Su Enterprise, un amministratore imposta ciascun namespace per registrare le immagini non firmate oppure per rifiutarle, e porta i namespace al rifiuto uno alla volta, così la produzione finisce per eseguire solo immagini costruite e firmate dalla pipeline. La firma fa parte della build, non è qualcosa da aggiungere prima di una release.
La regola che attraversa tutto questo è che una firma non valida è un rifiuto, mai un avviso. Un controllo che riceve SIG_INVALID si ferma. Non ricade sulla versione non firmata e non prosegue con una nota in un log, perché un avviso in un log di build è un via libera per chiunque non lo abbia letto.
La stessa regola si applica a tutto ciò che consegna su supporto fisico. Un bundle sigillato per un cliente air-gapped viene verificato rispetto alla Sua chiave pubblica prima che qualsiasi cosa venga estratta, e il capitolo 2.25, Sviluppare per ciascuna edizione, mostra il comando.
Identità di distribuzione
Un plugin viene distribuito attraverso diversi elementi, ciascuno con un nome: i suoi repository, una chiave di firma, un namespace di deploy, un prefisso di registry, uno schema di database, un insieme di domini e una policy di modifica. Ognuno di essi è un punto in cui due plugin potrebbero entrare in conflitto, o un plugin potrebbe divergere. L'identità di distribuzione è un unico record firmato per plugin che li contiene tutti, così ogni controllo lungo il percorso di rilascio legge la stessa risposta e rifiuta in caso di discrepanza.
Lei fornisce la Sua parte tramite il manifest e nient'altro: schema, db, domains, changePolicy e l'URL del repository. La piattaforma completa il record con il resto e lo firma. Non indica mai il proprio namespace, prefisso di registry o chiave di firma. Questi Le vengono assegnati, e un manifest che tentasse di dichiararli avanzerebbe una pretesa che i controlli dovrebbero poi smentire.
Il record firmato contiene undici campi: lo slug del plugin, l'organizzazione proprietaria, l'organizzazione che lo costruisce, i suoi repository, il nome della sua chiave di firma, il suo namespace di deploy, il suo prefisso di registry, il suo schema di database, i suoi domini, la sua policy di modifica e un breve elenco di nomi di immagine precedenti usati prima che esistesse il suo prefisso di registry. Quest'ultimo elenco può solo ridursi. Poiché è firmato, una nuova firma può rimuovere una voce e nulla può aggiungerne una di nascosto. La firma è Ed25519 sulla forma JSON canonica standard di quegli undici campi, così un record contenente "Tomás" o "Sinéad" viene verificato allo stesso modo ovunque.
Quando una release non corrisponde al suo record, prevale il primo rifiuto:
| Codice | Quando | HTTP |
|---|---|---|
DELIVERY_IDENTITY_MISSING |
Non esiste alcun record per il plugin | 403 |
DELIVERY_PATH_REFUSED |
Un push di immagine al di fuori del prefisso di registry che non è nell'elenco firmato dei nomi precedenti | 403 |
NAMESPACE_MISMATCH |
Un deployment destinato a un altro namespace | 403 |
IMAGE_NAME_COLLISION |
Un nome di immagine già rivendicato da un altro plugin | 409 |
CHANGE_CLASS_NOT_PERMITTED |
Una classe di modifica non governata dalla policy | 403 |
IMAGE_NAME_COLLISION è quello che sorprende le persone. Scelga un altro nome, e non ne riutilizzi mai uno: un nome di immagine condiviso significa che la promozione di un plugin può spostare i pod di un altro plugin.
Migrazioni, confermate e con ambito definito
Una migrazione viene distribuita all'interno dell'immagine del plugin ed è eseguita prima dell'avvio della nuova versione, tramite l'unico migration runner dell'SDK, nexus-migrate. Non deve scrivere un proprio applicatore. Prima che una release possa avanzare, lo stesso runner applica le migrazioni un file alla volta su un database usa e getta, così una migrazione che fallisce fallisce lì. La shadow build del template chiama il runner una volta per file, in ordine, e registra ogni file come farà la produzione.
Le regole del runner sono quelle verificate dai controlli, scritte come codice:
- Si connette con il ruolo migrator del Suo schema ed esegue ogni file come proprietario dello schema. Qualsiasi altro login, a cominciare da un superuser, viene rifiutato. Un file che tenta di cambiare ruolo da sé viene rifiutato prima che venga eseguito qualsiasi cosa.
- Il file di tenancy, numerato 0, non viene mai modificato dopo essere stato applicato. Una modifica alla tenancy ha un proprio file di revisione,
000_tenancy_r<N>.sql, chenexus-tenancy render --revision <N>scrive per Lei. - Normalmente il runner gestisce la transazione di ciascun file e rifiuta un
BEGINo unCOMMITal suo interno. Un file che gestisce le proprie transazioni dichiara di essere eseguito per singola istruzione, e allora ogniBEGINche apre deve avere una corrispondenza. - Tiene un registro, una riga per file, con lo SHA-256 del file e il modo in cui è stato eseguito. Un file applicato non viene mai modificato sul posto; una modifica è un nuovo file numerato.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sqlScoped significa che ogni nuova tabella contiene organization_id, owner_user_id e business_unit_id, più la colonna marcatore is_demo a meno che gates/demo-exempt.json non esenti la tabella con una motivazione, con una chiave primaria che inizia con l'organizzazione e chiavi esterne che la riportano, e con la sicurezza a livello di riga forzata. Il controllo migrations-are-scoped verifica queste regole su ogni file, e migrations-commit-what-they-open conta che ogni file esegua il commit di ciò che apre. Il secondo controllo esiste perché una migrazione che aveva eseguito un rollback silenzioso una volta è terminata con 0, e la tabella che avrebbe dovuto creare non è mai esistita.
Un altro file fa parte di ogni release. scripts/ci/required-env stampa le variabili d'ambiente di cui il Suo servizio ha bisogno per avviarsi, come array JSON ricavato dal Suo config loader. Il percorso di rilascio lo esegue e rifiuta una release il cui deployment non le imposta tutte, così una variabile mancante viene intercettata prima della release, non da un pod che non si avvia.
node scripts/ci/required-envRilascio delle skill
I due tipi di skill raggiungono le persone per vie diverse, quindi vanno rilasciati in modo diverso.
Una skill del manifest, una riga tipizzata nel skills[] del plugin, viene distribuita con il plugin e segue la stessa promozione del resto. L'onboarding sincronizza l'intero insieme di skill con il registry a ogni release. Se una skill viene esclusa dall'insieme, risulta disattivata, e su Enterprise una sincronizzazione con una skill non valida non ne applica nessuna, così continua a funzionare la versione precedente anziché metà di quella nuova.
Una skill di Skills Engine viene pubblicata dalla libreria. Su Enterprise, una skill che aggiunge uno strumento di scrittura attende l'approvazione di due persone designate tramite le loro passkey, e chi la propone non può essere una di loro. Una versione approvata viene quindi eseguita in modalità shadow, poi in canary per un'unità dietro gate designati, poi per tutti, e si arresta da sola se un gate non viene soddisfatto. Se il Suo plugin e una skill di Skills Engine dipendono l'uno dall'altra, pubblichi prima la skill e attenda che raggiunga tutti prima che la release del plugin che la richiama esca dalla fase pilota.
Canali e installazioni
Una volta che una release ha superato la fase pilota e raggiunto tutte le unità, viene offerta su un canale, e ciascuna unità sceglie il proprio canale. Il suo amministratore approva ogni passaggio. La pagina Canali e installazioni mostra quali unità eseguono quale versione, con i tassi di errore espressi solo come conteggi: Lei vede come si comporta la Sua estensione, mai che cosa qualcuno ne abbia fatto.
Il nostro plugin carrier-sync esegue tre versioni contemporaneamente, ed è normale. La maggior parte delle unità utilizza la release corrente, un'unità resta su una versione precedente in un canale mantenuto fino a una data dichiarata, e una release candidate si trova su un canale che nessuno ha ancora scelto. Non lo contrasti: un'unità che necessita di stabilità per un audit ne ha diritto.
Log e metriche dell'estensione
La pagina dei log e delle metriche del Suo pack è limitata ai Suoi carichi di lavoro, nelle unità in cui Le è consentito guardare. Può filtrare per unità e ambiente, e vede conteggi, tempi e stati.
I campi personali vengono sostituiti prima che una riga venga scritta, e i contenuti dei clienti, come il testo dei reclami, la posta o il contenuto dei documenti, non vengono mai scritti nei log. I log vengono conservati per 14 giorni. L'organizzazione è impostata dal gateway, mai dalla Sua query, pertanto una query che indica un'altra organizzazione viene rifiutata con TENANT_BOUNDARY. L'assistente nel dock può leggere gli stessi log insieme a Lei, e solo questi: quando gli ho chiesto perché una mattina i record delle escursioni fossero arrivati in ritardo, ha ricondotto 18 minuti di nuovi tentativi a letture duplicate provenienti dall'alimentazione elettrica di una banchina.
Rollback
Esistono due tipi di rollback, ed entrambi sono modifiche revisionate anziché semplici interruttori.
Il rollback di un ambiente utilizza la versione precedente. Ogni ambiente la conserva per 30 giorni. Il rollback viene preparato come modifica alla release, mostra un'anteprima di ciò che farà e richiede una seconda persona; una volta approvato, la pipeline esegue il rollback in circa un minuto. Ogni rollback viene cronometrato, così come ogni esercitazione, quindi ne provi uno prima di averne bisogno. Il rollback di una singola unità utilizza la pagina Canali e installazioni. La finestra modale di rollback indica che cosa cambia (quell'unità esegue di nuovo la versione precedente, e il suo tasso di errore viene monitorato per un'ora), che cosa resta invariato (le altre unità, e le impostazioni e i record dell'unità), il motivo, e chi è la seconda persona: l'amministratore di quell'unità.
Impostazioni e record vengono mantenuti durante un rollback, quindi pianifichi ogni release partendo dal presupposto che la versione precedente possa essere eseguita di nuovo sui dati scritti da quella più recente. È questo il motivo pratico per mantenere le migrazioni additive all'interno di una release di cui potrebbe essere necessario il rollback, ed è il motivo per cui chiediamo a due persone di approvarle una per una. Lo stesso vale per una modifica del modello: un revisore può, e dovrebbe, chiedere il piano di rollback di una richiesta di modifica del grafo prima di approvarla.
Il rollback delle skill è più graduale. Riportare l'etichetta live a una versione precedente richiede un solo passaggio, e le esecuzioni già in corso terminano con la versione con cui sono iniziate.
Ritiro di una versione
Una release, una volta creata, non viene mai modificata. Una versione che non deve più essere utilizzata viene ritirata, e una correzione viene rilasciata con un nuovo numero di versione. I canali di rilascio dell'SDK seguono la stessa prassi: una versione difettosa dell'SDK viene ritirata, mai sostituita con contenuti diversi sotto lo stesso numero. Adotti questa prassi, perché un numero di versione che può indicare due build diverse rende priva di valore ogni prova che la riguarda.
Il ritiro di un plugin o di un pack blocca le nuove installazioni. Le unità mantengono la versione che eseguono finché non effettuano il passaggio, quindi il ritiro è un segnale e una scadenza, non un interruttore di spegnimento. Comunichi agli amministratori delle unità a quale versione passare ed entro quando.
Il ritiro di una skill segue lo stesso principio con un passaggio in più. Skills Engine sposta tutti i chiamanti rimanenti su una sostituta dopo averne eseguito i casi, blocca le nuove esecuzioni e conserva le versioni, i casi e i record di esecuzione sigillati, in modo che la skill possa essere ripristinata se la sostituta si rivelasse inadeguata.
Checklist di rilascio
Questo è l'elenco che leggiamo prima di ogni release di Cold chain. È breve perché la piattaforma ne verifica la maggior parte al posto nostro.
- Le versioni sono allineate: il manifest,
pack.json, e il modello di conoscenza se è cambiato. - Ogni gate è verde in locale, partendo da un ambiente pulito, e ogni nuovo test ha dimostrato di fallire prima.
- La pagina Manifest e autorizzazioni non mostra alcun ampliamento, oppure l'ampliamento è quello voluto e i revisori ne conoscono il motivo.
- Ogni migrazione è un nuovo file numerato, con ambito definito, e applicato correttamente su un database temporaneo.
scripts/ci/required-envelenca ogni variabile necessaria al servizio, e il deployment imposta ciascuna di esse.- Il piano di rollback è descritto nella modifica, anche per qualsiasi modifica del modello.
- Due revisori diversi dall'autore sono disponibili questa settimana.
L'ultimo punto sembra banale. È quello che ha ritardato più release di tutti i gate messi insieme.



