AccediPrenota un briefing

Capitolo 2.15

Giorno due: gestione operativa di Nexus

Il lavoro di routine per gestire un'installazione dopo la prima settimana. Inizia con lo sblocco dell'archivio delle chiavi dopo un riavvio e termina con la disinstallazione.

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

18 minuti di lettura

La prima volta che è mancata la corrente nella sala server di Harrow Port Authority, tutto è ripartito tranne le parti che richiedevano le chiavi. I pod erano in stato Running e la console si caricava. Nessuno riusciva ad aprire un file. Tomás Reilly aveva letto a riguardo, ma gli ci sono voluti comunque venti minuti per ricordare il perché. L'unsealer del key store si avvia sigillato dopo ogni riavvio del suo nodo, e solo un custode può aprirlo.

Questo capitolo segue la routine dell'operatore dopo la prima settimana, dal key store e i suoi custodi fino alla disinstallazione. Ogni verbo di nexusctl qui accetta --explain, che stampa le operazioni kubectl e helm che eseguirebbe senza effettivamente eseguirle. Lo usi la prima volta che esegue qualsiasi operazione su un cluster di produzione.

Custodia dell'archivio delle chiavi

Un'installazione ha due server OpenBao nel proprio namespace. Il key store, openbao, conserva ogni chiave utilizzata da Nexus. L'unsealer, openbao-unsealer, è un secondo OpenBao di piccole dimensioni il cui unico compito è sbloccare il key store. Il key store si sblocca autonomamente tramite la chiave transit dell'unsealer; l'unsealer è sigillato con lo schema di Shamir, suddiviso in 5 quote di cui 3 qualsiasi bastano per sbloccarlo.

Alla prima installazione, un Job di custodia inizializza entrambi i server all'interno del cluster. Crittografa nella propria memoria le quote dell'unsealer e le chiavi di ripristino del key store per ogni custode indicato in keys.custody.recipients, e memorizza solo il testo cifrato (i Secret openbao-unseal-shares-encrypted e openbao-recovery-keys-encrypted). Revoca entrambi i root token nello stesso Job. Il pacchetto di ciascun custode contiene quote sufficienti per eseguire lo sblocco in autonomia, quindi dopo un riavvio basta un solo custode.

Dopo il riavvio di un nodo

Dopo qualsiasi riavvio del nodo su cui gira l'unsealer (un'interruzione di corrente, un riavvio della macchina, un riavvio del container runtime), l'unsealer si avvia sigillato. Finché un custode non lo sblocca, anche il key store rimane sigillato e nulla che richieda una chiave può funzionare. La console continua a rispondere e le persone possono ancora accedere, ma qualsiasi operazione che necessiti di una chiave dal key store rimane in attesa: l'apertura di contenuti crittografati, un claim, la verifica di una parte compilata.

Interroghi direttamente OpenBao, all'interno di ciascun pod. Questo è l'unsealer:

kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
  bao status -format=json -address=https://127.0.0.1:8200 \
  -ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"

Esegua lo stesso comando su openbao-0 con -tls-server-name=openbao per il key store. bao status restituisce il codice di uscita 0 quando il server è sbloccato, 2 quando è sigillato e 1 quando non è riuscito a rispondere. Un codice di uscita 1 non permette di trarre conclusioni, perché il pod potrebbe non essere ancora attivo. Attenda un minuto e riprovi. Se l'unsealer è sbloccato e il key store è ancora sigillato, il key store si sta sbloccando da solo e non occorre fare nulla.

A sinistra: l'icona di una persona con l'etichetta "Custode, con la propria identità age". Una freccia va verso destra in un riquadro "unseal.sh sulla macchina del custode (una decrittografia)". Da lì una freccia con l'etichetta "kubectl port-forward, Transport Layer Security (TLS) verificato rispetto alla certificate authority (CA) dell'unsealer" entra in un riquadro "openbao-unsealer (Shamir 5 quote, 3 qualsiasi)". Dall'unsealer una seconda freccia con l'etichetta "chiave transit, automatica" entra in un riquadro "openbao, il key store". Dal key store parte un ventaglio di frecce verso piccoli riquadri "nexus-keys", "nexus-auth", "gli altri servizi". Una nota sotto il custode: "l'identità non lascia mai questa macchina".
Cosa fa un custode dopo il riavvio di un nodo.

Sblocco

Il chart include unseal.sh, nella cartella files/custody/, identico byte per byte in ogni release. Un custode lo esegue sulla propria macchina. Lo script legge il Secret crittografato, lo decrittografa una sola volta con l'identità del custode (un'identità su Secure Enclave richiede Touch ID una volta), invia le quote all'unsealer e conferma che sia sbloccato. Nessuna quota viene mai scritta su file o passata sulla riga di comando.

Harrow lo esegue in modalità diretta, tramite un port-forward:

kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &

AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh

<path-to-your-custodian-identity> è il file di identità age del custode, la metà privata di uno dei destinatari in keys.custody.recipients. UNSEAL_RESOLVE è il nome riportato sul certificato dell'unsealer (<namespace> è il namespace in cui è installato Nexus, nexus per impostazione predefinita), pertanto TLS viene verificato rispetto alla CA propria dell'unsealer anche se la connessione è diretta a 127.0.0.1. Lo script non disattiva mai la verifica del certificato.

Uscita Ultima riga Significato
0 UNSEALED nexus/openbao-unsealer-0 Sbloccato. Se lo era già, non è stato inviato nulla
1 STILL-SEALED … Ancora sigillato, oppure una chiamata di sblocco non è riuscita
2 UNSEAL-REFUSED … Manca un prerequisito, indicato nel messaggio
3 UNSEAL-REFUSED … Questa identità non può decrittografare le quote, quindi non appartiene a un custode di questa installazione. Non è stato inviato nulla

Entro un minuto il key store segue autonomamente. Verifichi con kubectl -n nexus get deploy,statefulset che tutto sia di nuovo pronto.

I custodi vengono scelti prima dell'installazione e ciascuno genera la propria chiave sulla propria macchina. Il chart vede unicamente la metà pubblica:

age-keygen -o custodian.key
age-plugin-se keygen --access-control=any-biometry -o custodian.key

Il primo comando crea un'identità age ordinaria; il suo destinatario è la riga # public key: age1... nel file. Il secondo ne crea una custodita nel Secure Enclave di un Mac, con un destinatario che inizia con age1se1. L'uno o l'altro destinatario va inserito in keys.custody.recipients. Il file di identità rimane al suo custode, offline.

Backup e ripristino

Backup e ripristino mostra ciascuno store con l'ultimo backup e l'ultima volta in cui ne è stato effettivamente testato il ripristino. Un backup è comprovato solo una volta che è stato ripristinato, quindi la pagina tiene traccia di entrambi gli eventi. Vengono sottoposti a backup sei store. Il database principale contiene persone e impostazioni, job e registro di audit. Accanto ad esso si trovano il grafo della conoscenza e l'indice di ricerca, poi il file store e il memory store. Le chiavi costituiscono il sesto, sigillate e tenute separate dai dati. I backup vengono salvati sul suo spazio di archiviazione, crittografati con le sue chiavi, e Adverant non può leggerli. Quando per uno store non viene eseguito un ripristino di prova entro i termini della regola impostata, la pagina mostra il riquadro RESTORE_TEST_OVERDUE con il pulsante Provalo ora. Un ripristino di prova viene eseguito in uno spazio separato e nessuno se ne accorge.

Le stesse due operazioni sono disponibili dalla riga di comando:

nexusctl backup now
nexusctl backup verify

backup now esegue il backup di tutti gli store contemporaneamente. backup verify verifica l'ultimo backup. Li esegua entrambi prima di qualsiasi modifica che le desti preoccupazione.

Backup e ripristino
Backup e ripristino
Ciascuno store con il suo ultimo backup e il suo ultimo ripristino testato. L'indice di ricerca è in ritardo per un test e il riquadro propone di eseguirne uno ora.

Per ripristinare, indichi il nome del backup:

nexusctl restore --from <backup-id>

<backup-id> proviene dall'elenco nella pagina Backup e ripristino. Un ripristino richiede l'approvazione di una seconda persona e, mentre è in corso, la barra di avanzamento lo mostra indicando l'ora di inizio e chi lo ha approvato. Durante il ripristino tutti gli utenti sono in sola lettura, il che è diverso dall'essere bloccati fuori: le persone possono accedere e leggere. I job non partono (le pianificazioni attendono e recuperano in seguito) e la ricerca torna disponibile quando l'indice di ricerca è stato ripristinato. Tutto ciò che è stato scritto dopo l'esecuzione del backup va perso; il report di ripristino lo elenca per proprietario in modo che possa essere rifatto.

Ripristino in corso
Ripristino in corso
Un ripristino in corso. Gli store tornano operativi in ordine, gli utenti sono in sola lettura finché non è stato caricato l'ultimo e un avviso su ogni pagina indica quando è previsto il ritorno alla normalità.

Conservi un'altra cosa insieme ai backup: il Secret nexus-generated nel namespace nexus. Il chart crea le password generate e le chiavi di crittografia dell'installazione alla prima installazione e le rilegge da quel Secret a ogni aggiornamento. I dati sigillati sotto EXTERNAL_KEY_ENCRYPTION_KEY si aprono solo con quella chiave. Conservi una copia del Secret nello stesso luogo in cui custodisce il materiale più sensibile di cui dispone, perché chiunque lo possieda possiede quelle chiavi.

Aggiornamenti

Tomás esegue l'aggiornamento in due passaggi. Prima chiede che cosa cambierà:

nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

Il piano elenca cosa cambia nella release, eventuali modifiche alla struttura del database e se l'operazione sia annullabile. Quindi lo applica:

nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

Il comando apply esegue prima un backup e avvia i controlli preflight. Sposta poi i motori a ondate, e ciascuna ondata attende che la precedente sia rimasta in stato integro per 10 minuti. La pagina Aggiornamento mostra ogni ondata man mano che procede e lo stato di salute dell'installazione nel frattempo. Indica anche fino a quando rimane aperta la possibilità di tornare indietro; dopo tale data, per tornare alla versione precedente occorre un ripristino. Se un passaggio non riesce, Nexus riporta tutti i motori alla release precedente e li verifica. L'avviso UPGRADE_ROLLED_BACK indica quindi il passaggio non riuscito e conferma che i dati non sono stati modificati. La correzione viene mostrata prima di Riprova, e il pacchetto di supporto è a portata di clic.

Per un'installazione priva di connessione esterna il pacchetto arriva su supporto fisico. L'importazione da supporto verifica la firma della release rispetto alla chiave di rilascio di Adverant presente sull'installazione e controlla che le versioni procedano solo in avanti. I file firmati da chiunque altro vengono rifiutati con MEDIA_SIGNATURE_INVALID: non viene caricato nulla e la release in esecuzione continua a funzionare.

Aggiornamento
Aggiornamento
Un aggiornamento in corso. È stato prima eseguito un backup, la seconda di tre ondate è in movimento e la possibilità di tornare indietro rimane aperta fino alla data indicata.
Aggiornamento non riuscito e annullato
Aggiornamento non riuscito e annullato
Un'ondata non è riuscita perché un volume ha esaurito lo spazio. Tutti i motori sono tornati alla release precedente con i dati intatti, e la correzione è elencata prima di Riprova.

Cosa succede dietro le quinte

nexusctl upgrade apply esegue helm upgrade sul chart. Se esegue l'aggiornamento direttamente con Helm, valgono le stesse regole:

helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s

Lo schema viene aggiornato prima dell'avvio dei nuovi pod. Le migrazioni del chart sono hook pre-upgrade eseguiti in ordine: prima il bootstrap del database, poi le migrazioni di ciascun servizio, infine quelle del backend for frontend (BFF) della console. Viene eseguito anche il Job di custodia che, su un'installazione già inizializzata, si limita a confermarlo senza modificare nulla. Ogni Job di hook ha un limite di backoff pari a 0, quindi una migrazione che fallisce interrompe l'aggiornamento e non viene mai ritentata silenziosamente: ne legga il log con kubectl -n nexus logs job/<hook-job> prima di riprovare.

Il pod di ciascun servizio attende in un init container, wait-for-schema, finché il registro delle release non mostra che le relative migrazioni sono state applicate per l'immagine della nuova release. Dopo un rollback, o dopo un aggiornamento che ha modificato solo i valori, un pod riavviato trova già la propria riga e si avvia immediatamente.

Prima dell'aggiornamento

Tre punti delle note di rilascio meritano di essere pianificati con attenzione:

  1. Eseguire l'aggiornamento in un periodo di basso traffico. Al primo aggiornamento di un'installazione creata con un chart precedente, il job di bootstrap rimuove i vecchi diritti predefiniti sulle tabelle e ciascun servizio riacquisisce i propri tramite la propria migrazione. Finché tale migrazione non viene eseguita, un servizio non può usare le proprie tabelle. L'intervallo dura pochi secondi. Se anche pochi secondi sono critici, riduca prima i servizi a zero repliche e li riporti a regime una volta terminati i job di migrazione.
  2. Associare un'organizzazione a ogni chiave di application programming interface (API). Una chiave priva di organizzazione viene rifiutata con 403 TOKEN_ORG_MISSING da ogni servizio che verifica le chiavi tramite nexus-auth, incluso nexus-graphrag. Prima di aggiornare, associ un'organizzazione a ciascuna di queste chiavi oppure emetta una nuova chiave. Le vecchie chiavi bcrypt continuano a funzionare fino alla loro data di revoca definitiva.
  3. Svuotare successivamente la cache delle chiavi API. Fino a un'ora di voci di chiavi memorizzate nella cache riporterà il nome dell'applicazione errato finché non verrà eseguita questa operazione. Esegua questo comando sulla cache di nexus-auth, il Valkey dell'installazione (nexus-valkey, password nel Secret nexus-generated sotto VALKEY_PASSWORD):
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
  'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"

Questo vale per lo store predefinito interno al cluster. Con dataTier.valkey.mode: external tale pod non esiste: esegua la stessa scansione e cancellazione sul suo host Valkey, utilizzando la password presente nel Secret indicato in dataTier.valkey.external.existingSecret.

Rollback

Entro la finestra temporale mostrata nella pagina Aggiornamento, Torna indietro riporta ogni motore alla release precedente. Una volta chiusa la finestra, tornare indietro significa ripristinare il backup eseguito prima dell'aggiornamento.

Due valori non devono mai cambiare durante un aggiornamento o un rollback.

keys.installationName è permanente. Il primo bootstrap del key store conia l'identità dell'installazione sulla base di esso, e tale identità è quella indicata nella licenza. Utilizzi esattamente lo stesso valore in ogni file values che applicherà a questa installazione.

Il Secret nexus-generated deve rimanere invariato. A ogni aggiornamento il chart legge EXTERNAL_KEY_ENCRYPTION_KEY da esso e ne verifica il formato. Un valore che non sia né la codifica base64 di 32 byte né la chiave grezza da 32 byte di un'installazione precedente interrompe il rendering con EXTERNAL_KEY_ENCRYPTION_KEY_INVALID, e il chart non stampa mai il valore. Ciò significa che qualcuno ha modificato o sostituito il Secret. Ripristini la chiave con cui sono sigillati i dati di questa installazione, in formato base64 dei suoi 32 byte (printf %s "$OLD" | base64), e ripeta l'aggiornamento. Una nuova chiave casuale renderebbe illeggibile tutto ciò che è stato sigillato con la vecchia.

Scalabilità

Ogni componente ha un interruttore di attivazione e una dimensione nel file values. I componenti obbligatori non possono essere disattivati: il chart li esegue indipendentemente dal valore del loro interruttore. Agli altri è possibile assegnare più repliche e più risorse.

# harrow-values.yaml (Helm values): scaling
components:
  gateway:
    replicas: 2
    resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
  graphrag:
    replicas: 2
  workflows:
    replicas: 2
workflows:
  concurrency: "8"
dataTier:
  qdrant:
    resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }

Applichi le modifiche con helm upgrade come indicato sopra. I volumi sono dimensionati sotto dataTier.<store>.size; verifichi che la sua classe di archiviazione supporti l'espansione di un volume prima di aumentarne la dimensione. La pagina Stato dell'installazione mostra in grafico quanto sono stati impegnati i processori e la memoria del cluster, con il margine rimanente per ciascuno. Espanda per primo l'elemento che si esaurisce prima.

Bundle di supporto

Quando Harrow ha bisogno dell'assistenza di Adverant, Tomás crea un pacchetto di supporto:

nexusctl support-bundle --out harrow-support-4471.tar.gz

La pagina Pacchetto di supporto della console genera lo stesso file. Raccoglie i log dei motori delle ultime 24 ore insieme ai dettagli sullo stato di salute e sulle versioni. Le impostazioni vengono incluse senza i relativi segreti, insieme ai report di preflight e di installazione. Prima che qualsiasi dato venga scritto, l'offuscamento sostituisce nomi e segreti con segnaposto e lei può leggere un'anteprima di ciò che verrà esattamente esportato. I contenuti degli utenti non vengono mai raccolti. Il pacchetto viene inviato ad Adverant tramite caricamento nella pagina Supporto e pacchetti di supporto del suo account oppure come file trasportato su supporto fisico. Solo i tecnici del supporto indicati nella richiesta possono aprirlo, e viene cancellato dopo 30 giorni.

Pacchetto di supporto
Pacchetto di supporto
Creazione di un pacchetto di supporto. L'anteprima di offuscamento mostra cosa viene nascosto prima che qualsiasi dato esca, e solo i tecnici indicati possono aprirlo.

Esportazione delle prove

I revisori e il suo team di conformità richiedono spesso la prova che la piattaforma si comporti come descritto. nexusctl evidence export la genera:

nexusctl evidence export --out harrow-evidence-2027-01

Oltre ai record che esporta, il comando esegue le sonde di accettazione della piattaforma: il router di intelligenza artificiale (IA) è raggiungibile e risponde, un job UNO viene inviato e completato, e una lettura tra organizzazioni diverse viene rifiutata. I relativi risultati si trovano in probes.json nella cartella di output.

Stato a colpo d'occhio

nexusctl status --json indica se l'installazione è integra e in quale stato si trova ciascun componente. Riporta inoltre lo stato della licenza con la relativa data di scadenza, l'edizione e la release in esecuzione. Ogni parte compilata è elencata con il proprio digest e la propria firma. È il comando da collegare al proprio sistema di monitoraggio.

Disinstallazione

nexusctl uninstall --profile <profile-file>

<profile-file> è il profilo di distribuzione per il cluster, lo stesso file passato a nexusctl handoff --profile <profile-file> --out <dir> se è il suo team di piattaforma a gestire il cluster. Handoff genera per quel team un elenco in linguaggio chiaro di ciò che Nexus richiede al cluster e i manifest per soddisfarlo. La disinstallazione rimuove esclusivamente i namespace di Nexus e conserva i backup. L'identità dell'installazione viene rimossa insieme ad essa. Un'installazione successiva sullo stesso cluster costituirà una nuova installazione con una nuova identità, pertanto avrà un nuovo claim e una nuova licenza.

Le pagine Questa installazione

Gli operatori dell'installazione dispongono di un proprio gruppo nel menu, Questa installazione, e le relative pagine sono il luogo della console in cui si svolge la maggior parte delle operazioni descritte in questo capitolo. Un membro che apre una di queste pagine visualizza la schermata Non sei un amministratore, che indica chi è autorizzato ad agire.

Pagina A cosa serve
La licenza e cosa sblocca La licenza e i relativi gruppi di funzionalità (capitolo 2.13, Licenze)
Se la licenza scade La sequenza di scadenza descritta a parole, con le date di questa licenza
Parti compilate Ogni modulo concesso in licenza con la verifica notturna della firma
Prospetto di utilizzo per Adverant I contatori annuali, consultabili prima dell'invio
Versioni e aggiornamenti Ogni versione installata, con chi l'ha installata e quando
Aggiornamento L'aggiornamento a fasi e la procedura per tornare indietro
Backup e ripristino Ogni store, il suo ultimo backup e il suo ultimo ripristino testato
Stato dell'installazione Nodi, capacità e costi operativi, con avvisi
Chiavi e cancellazione La chiave di ogni organizzazione e la funzione Cancella con motivazione e approvazione di una seconda persona
Incidenti Problemi aperti e chiusi, con le azioni intraprese
In via di dismissione Funzionalità in fase di disattivazione, con date, esportazione e sostituzione
Stato Ogni parte di Nexus adesso e negli ultimi 30 giorni, in un linguaggio comprensibile a chiunque
Pacchetto di supporto Cosa viene inviato ad Adverant e come

Due di queste pagine meritano un approfondimento. Parti compilate verifica ogni notte ciascun modulo concesso in licenza rispetto alla firma di Adverant. Una copia modificata di un modulo viene rifiutata e non viene mai caricata, mentre la copia firmata continua a funzionare; la pagina conteggia i rifiuti per mese in modo che una copia manomessa non possa passare inosservata. Stato è scritto in modo che chiunque nell'organizzazione possa leggerlo. Mostra ogni parte di Nexus adesso e negli ultimi 30 giorni sotto forma di striscia giornaliera, con le manutenzioni programmate e gli incidenti recenti, e un operatore può aggiungere un incidente o una finestra di manutenzione dalla stessa pagina.

Un'installazione Community ha una sola pagina, Questa installazione (Community), con la versione, lo stato di salute e gli aggiornamenti. Le pagine Enterprise vi compaiono come anteprime che indicano chi può attivarle.