Versione 1.0.0-alpha.1ultima
Capitolo 2.5
Controlli preliminari con nexusctl
Ogni verifica effettuata da `nexusctl preflight`, cosa legge ciascuna di esse e come fallisce, il report che stampa e salva, come tale report raggiunge la pagina preflight della console e tutti i flag.
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

Il nostro primo preflight presso Harrow Port Authority non ha superato quattro controlli, e due di questi ci sarebbero costati ben più di un pomeriggio. Avevamo iniziato il file dei valori copiando l'esempio del chart, e il preflight ha rifiutato sia il nome dell'installazione di esempio sia il custode di esempio. Nessuno possiede la chiave privata di quel custode. Un'installazione sigillata con essa non potrà mai essere sbloccata dopo il riavvio di un nodo. Il preflight lo ha rilevato in pochi secondi, prima che esistesse alcunché da perdere.
nexusctl preflight legge il cluster e il file dei valori, stampa ciò che ha trovato, salva un report e non modifica nulla sul cluster. Eseguitelo prima di ogni installazione e di ogni aggiornamento. Questo capitolo illustra ogni controllo effettuato, il formato del report, la sua destinazione e i flag.
Gestione operativa
Il preflight necessita di due elementi: il contesto kube del cluster su cui effettuerete l'installazione e il file dei valori che l'installazione utilizzerà. Scrivete prima il file dei valori; il capitolo 2.6, Installazione di Community su Kubernetes, esamina ogni chiave. Quindi:
nexusctl preflight --context harrow-prod --values harrow-values.yamlLegge il cluster tramite client-go utilizzando esclusivamente chiamate get e list. Se il vostro tls.mode è existing, create il namespace nexus e il Secret Transport Layer Security (TLS) prima di eseguirlo (capitolo 2.6, Installazione di Community su Kubernetes, passaggio 3), altrimenti il controllo del certificato segnalerà l'assenza del Secret.
| Flag | Cosa fa | Predefinito |
|---|---|---|
--context <name> |
Il contesto kube da controllare. Obbligatorio | nessuno |
--values <file> |
Il file dei valori che l'installazione utilizzerà. Obbligatorio | nessuno |
--namespace <name> |
Dove viene installato Nexus | nexus |
--release <version> |
La release sottoposta a controllo | la versione propria del chart incluso |
--report-dir <dir> |
Dove vengono salvati i due file di report | la cartella corrente |
--record <mode> |
auto, always o never: indica se consegnare il report al servizio chiavi di questa installazione, affinché la relativa pagina del programma di installazione lo mostri |
auto |
--kubeconfig <file> |
Il kubeconfig da leggere | KUBECONFIG, poi ~/.kube/config |
--ca-bundle <file> |
I vostri certificati dell'autorità di certificazione (CA), per una catena che i controlli devono considerare attendibile | nessuno |
--single-node |
Controlla una macchina per un'installazione su macchina singola (capitolo 2.8, Installazioni su macchina singola) | disattivato |
Il requisito minimo della release per Kubernetes non è codificato in nexusctl. Esso legge il limite inferiore di kubeVersion proprio del chart direttamente dal chart che include, pertanto il controllo e helm install non possono mai discordare.
Cosa stampa un'esecuzione
Ecco la prima esecuzione di Harrow, così come è stata stampata:
Adverant Nexus 1.0.0-alpha.1 · preflight · Tue 10 Nov 2026 08:40 · read-only
Failed first
FAIL Address (api) api.harrow.example → no record people reach Nexus by this name
fix add a DNS record for api.harrow.example that points at the ingress, then run preflight again
FAIL Address (auth) auth.harrow.example → no record people reach Nexus by this name
fix add a DNS record for auth.harrow.example that points at the ingress, then run preflight again
FAIL Key custodians the example custodian of the chart's values-community.yaml and values-enterprise.yaml (age1u63etg5v…) the key store seals its recovery keys to them; no one holds the example custodian's key
fix replace it in keys.custody.recipients in harrow-values.yaml with your custodians' own recipients: each custodian makes a key on their own machine with `age-keygen -o custodian.key` (the `# public key: age1...` line is the recipient), or `age-plugin-se keygen --access-control=any-biometry -o custodian.key` for a Secure Enclave key, keeps the identity file offline, and gives you only the recipient
FAIL Installation name nexus-example, the example name of the chart's values-community.yaml and values-enterprise.yaml the first key-store bootstrap mints the installation identity under it, permanently
fix set keys.installationName in harrow-values.yaml to this installation's own name
Warnings
warn Graphics nodes none the assistant will need a hosted model
fix add a node with a graphics card and its device plugin, or have the assistant use a hosted model
warn Certificate secret harrow-public-tls not found in nexus the public address needs it before people sign in
fix create the TLS secret harrow-public-tls in nexus before installing, or change tls.existingSecret in harrow-values.yaml
Passed
pass Kubernetes version 1.33.6+k3s1 needs 1.33 or later
pass Nodes ready 3 of 3
pass Storage class local-path (default)
pass Resources 24 cores, 93.9 GiB needs 2.1 cores, 6.7 GiB
pass Ingress class traefik (default)
pass Ingress ports traefik (LoadBalancer) on 80 and 443
pass Address (console) console.harrow.example → 10.20.4.10
────────────────────────────────────────────────────────────────────────────
7 passed · 2 warnings · 4 failed Install cannot continue until the failures pass.
Nothing was changed. Report saved to preflight-2026-11-10-0840.txt
Quando qualcosa non va a buon fine, vengono mostrati prima gli errori, poi gli avvisi e infine i controlli superati. Ogni riga mostra l'esito, il nome del controllo, ciò che è stato rilevato e ciò che è necessario; ogni riga relativa a un controllo non superato presenta una riga fix sottostante. Le ultime due righe sono il riepilogo e il file di report.
Abbiamo corretto i valori, aggiunto i due record del Domain Name System (DNS), creato il Secret e ripetuto l'esecuzione:
Adverant Nexus 1.0.0-alpha.1 · preflight · Thu 12 Nov 2026 09:02 · read-only
Cluster
pass Kubernetes version 1.33.6+k3s1 needs 1.33 or later
pass Nodes ready 3 of 3
pass Storage class local-path (default)
pass Resources 24 cores, 93.9 GiB needs 2.1 cores, 6.7 GiB
warn Graphics nodes none the assistant will need a hosted model
fix add a node with a graphics card and its device plugin, or have the assistant use a hosted model
Network
pass Ingress class traefik (default)
pass Ingress ports traefik (LoadBalancer) on 80 and 443
pass Address (console) console.harrow.example → 10.20.4.10
pass Address (api) api.harrow.example → 10.20.4.10
pass Address (auth) auth.harrow.example → 10.20.4.10
pass Certificate ends 3 Nov 2027
Time and keys
pass Key custodians 3 custodians
pass Installation name harrow-port-authority
────────────────────────────────────────────────────────────────────────────
12 passed · 1 warning · 0 failed You can install. Warnings do not block; fix them when you can.
Report saved to preflight-2026-11-12-0902.txt · nothing was changed on the cluster
Un'esecuzione senza errori elenca i controlli sotto le rispettive tre intestazioni: Cluster, Rete, e Orario e chiavi. Gli avvisi non sono mai bloccanti. Abbiamo mantenuto l'avviso relativo alla grafica di proposito: su questo cluster pilota connesso, l'assistente di Harrow utilizzava un modello ospitato con la chiave propria del porto.
Codici di uscita
| Codice | Significato |
|---|---|
0 |
L'installazione può procedere. Gli avvisi non sono bloccanti |
1 |
L'installazione è bloccata: almeno un controllo non è stato superato |
2 |
Impossibile eseguire il preflight: non è stato possibile leggere il kubeconfig, il contesto, il file dei valori o l'interfaccia di programmazione delle applicazioni (API) del cluster, oppure un flag era errato |
Gli script dovrebbero leggere il codice di uscita, non il testo. Il nostro esegue il preflight come primo passaggio di ogni aggiornamento e si interrompe con qualsiasi valore diverso da 0.
Eseguite il nexusctl della release a cui state passando, non quello con cui avete effettuato l'installazione. I requisiti provengono dal chart che esso include, quindi una release più recente può innalzare il requisito minimo di Kubernetes o richiedere più memoria, e solo il suo nexusctl ne è a conoscenza. --release modifica la versione nominata nel report; non modifica il chart di cui vengono applicate le regole. Presso Harrow conserviamo il nexusctl di ogni release accanto al relativo chart nel registro delle modifiche, in modo che un eventuale rollback venga verificato dallo strumento corrispondente.
Ogni verifica
Vi sono undici controlli. Dieci di essi producono una riga ciascuno; il controllo degli indirizzi produce una riga per host, pertanto un'esecuzione completa conta tredici righe. Nove controlli devono essere superati obbligatoriamente e un esito negativo costituisce un errore. Due controlli, i nodi grafici e il certificato, dovrebbero essere superati e un esito negativo costituisce un avviso. L'ultima colonna è il testo del requisito che ogni riga riporta nel report; al suo interno, CPU indica l'unità di elaborazione centrale.
| ID controllo | Sezione | Superamento obbligatorio | Requisito stampato |
|---|---|---|---|
kubernetes-version |
cluster | sì | Kubernetes 1.33 o successivo |
nodes-ready |
cluster | sì | Ogni nodo pronto |
storage-class |
cluster | sì | Una classe di archiviazione per i dati |
resources |
cluster | sì | CPU e memoria sufficienti per la release |
graphics-nodes |
cluster | no | Nodi grafici |
ingress-class |
network | sì | Una classe di ingress per i tre indirizzi |
ingress-ports |
network | sì | Il controller di ingress aperto sulle porte 80 e 443 |
address-console, address-api, address-auth |
network | sì | L'indirizzo console, api o auth viene risolto nel DNS |
certificate |
network | no | Certificato valido per altri 30 giorni |
custodians |
time-and-keys | sì | Le persone che detengono le chiavi di ripristino di questa installazione |
installation-name |
time-and-keys | sì | Il nome permanente proprio di questa installazione |
kubernetes-version
Legge la versione dell'API server e la confronta con il requisito minimo del chart. Trova, ad esempio, 1.33.6+k3s1. Al di sotto della versione 1.33 restituisce un errore con la soluzione upgrade the cluster to 1.33 or later. Se la stringa della versione non è leggibile da nexusctl, restituisce un errore anziché tirare a indovinare.
nodes-ready
Elenca i nodi e conta quelli la cui condizione Ready è true, come 3 of 3. Qualsiasi nodo non pronto viene nominato, e la soluzione indica di riportarlo allo stato Ready e di leggerne le condizioni. Un cluster del tutto privo di nodi non supera il controllo, suggerendo che il contesto potrebbe puntare al cluster errato.
storage-class
Se i vostri valori impostano storage.className, il controllo cerca tale classe e restituisce un errore con <name> does not exist se è assente. In caso contrario, cerca una classe contrassegnata come predefinita e la riporta come local-path (default). In assenza di una classe predefinita restituisce un errore con none marked default, e la colonna dei requisiti spiega perché ciò è importante: the database cannot claim a disk. Se due classi sono contrassegnate come predefinite, il cluster assegna a una nuova richiesta quella più recente, che sarà quindi quella riportata.
resources
Calcola ciò che la release richiede in base al chart e ai vostri valori, quindi somma i core dell'unità di elaborazione centrale (CPU) e la memoria allocabili di ogni nodo che sia Ready, non sottoposto a cordon e privo di taint NoSchedule o NoExecute. I pod del chart non hanno toleration, pertanto un nodo con taint non può eseguirli e non viene conteggiato. Un cluster con risorse insufficienti non supera il controllo indicando l'esatta carenza, ad esempio add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Il fabbisogno viene arrotondato per eccesso e la disponibilità per difetto, in modo che il controllo non faccia mai stime troppo ottimistiche.
graphics-nodes
Cerca un nodo Ready dotato di un'unità di elaborazione grafica (GPU) allocabile, nvidia.com/gpu. In sua assenza genera un avviso: the assistant will need a hosted model. Il preflight lo tratta come un suggerimento e non blocca mai l'operazione per questo motivo, poiché l'assistente può rispondere invece tramite un modello di intelligenza artificiale (IA) ospitato. Il capitolo 2.14, Provider e modelli di IA, illustra entrambi i percorsi.
ingress-class
Se ingress.className è impostato, il controllo cerca tale classe. In caso contrario, cerca esattamente una classe contrassegnata come predefinita. Anche due classi contrassegnate come predefinite causano un errore, poiché in tal caso l'API server rifiuta un Ingress privo di classe. Il controllo viene ignorato, e la relativa riga omessa, quando ingress.enabled è impostato su false.
ingress-ports
Cerca nel namespace indicato da networkPolicy.ingressNamespace (per impostazione predefinita kube-system, dove k3s esegue Traefik) un Service di tipo LoadBalancer o NodePort che esponga sia la porta 80 sia la 443. La policy di rete del chart consente solo a tale namespace di raggiungere i tre Service pubblici, pertanto un controller di ingress situato altrove non potrebbe servire Nexus nemmeno se fosse in ascolto. La soluzione indica entrambe le alternative: esporre il controller in tale posizione, oppure impostare networkPolicy.ingressNamespace sul namespace in cui è in esecuzione. Ignorato quando ingress.enabled è false.
address
Cerca hosts.console, hosts.api e hosts.auth dalla vostra workstation, per cinque secondi ciascuno, e stampa una riga per host. Un host privo di record non supera il controllo con <host> → no record. Un host non impostato non supera il controllo con hosts.<key> is not set. Quando un nome ha più indirizzi, la riga mostra il primo, IPv4 prima di IPv6, e indica quanti altri ce ne sono.
certificate
Viene eseguito solo quando tls.mode è existing e tls.existingSecret nomina un Secret; con cert-manager o none non vi è alcun vostro certificato da leggere e la riga viene omessa. Legge tls.crt dal Secret nel namespace di installazione e nient'altro. Un certificato valido per 30 giorni o più supera il controllo come ends 3 Nov 2027. Uno che scade prima genera l'avviso ends in 9 days; uno già scaduto genera l'avviso ended 4 days ago. Un Secret mancante, o privo di certificato al suo interno, genera un avviso con la relativa soluzione.
custodians
Legge keys.custody.recipients. Se non ve ne sono, restituisce un errore con il codice KEYS_CUSTODIAN_MISSING. Se un destinatario qualsiasi è il custode di esempio proveniente dai file dei valori propri del chart, restituisce un errore con KEYS_CUSTODIAN_EXAMPLE, poiché nessuno detiene quella chiave e le chiavi di ripristino dell'installazione verrebbero sigillate senza alcun destinatario reale. Se il controllo viene superato, viene stampato il conteggio, ad esempio 3 custodians.
installation-name
Legge keys.installationName. Se non è impostato, restituisce un errore con INSTALLATION_NAME_MISSING. Se è impostato sul nome di esempio proveniente dai file dei valori del chart, restituisce un errore con INSTALLATION_NAME_EXAMPLE. Se il controllo viene superato, stampa il nome. La colonna dei requisiti spiega perché questo controllo è più importante della maggior parte degli altri: the first key-store bootstrap mints the installation identity under it, permanently.
Gli ultimi due controlli riportano esattamente i codici con cui il chart stesso rifiuta un'installazione. Il preflight ve lo comunica semplicemente in anticipo, prima che Helm abbia creato alcunché.
I file del report
Ogni esecuzione salva due file in --report-dir, denominati in base all'ora di esecuzione: preflight-2026-11-12-0902.txt, le righe così come sono state stampate senza codici colore, e preflight-2026-11-12-0902.json, la medesima esecuzione in un formato fisso leggibile da un programma. L'output del terminale e le righe salvate provengono dallo stesso elenco, pertanto non differiscono mai.
Il report JSON segue lo schema nexus.preflight/v1:
| Campo | Contenuto |
|---|---|
schema |
Esattamente nexus.preflight/v1 |
tool |
Un oggetto: name (nexusctl) e version |
release |
La release controllata |
ran_at |
Quando è stato eseguito, secondo il tempo coordinato universale (UTC) |
context |
Il nome del contesto kube |
values |
Solo il nome di base del file dei valori |
read_only |
Sempre true |
checks |
Una voce per riga: id, section, name, requirement, must_pass, outcome (pass, warn o fail), found, needs, fix e, in caso di mancato superamento con una causa leggibile dalla macchina, code |
counts |
passed, warnings e failed |
can_install |
true quando non si sono verificati errori |
report_file |
Il nome del file .txt |
transcript |
Un oggetto: title (nexusctl preflight) e lines, ogni riga con il proprio kind (prompt, ok, warn, bad, note, out o blank), il proprio text e at, e talvolta marks |
Il report è progettato per essere mostrato prima che chiunque effettui l'accesso, pertanto non contiene alcun nome utente, nome host della workstation, percorso di file, token né alcunché proveniente dal vostro kubeconfig. values è un nome di base e context è il nome del contesto. Se il report di un'esecuzione dovesse violare una qualsiasi di queste regole, nexusctl si rifiuta di stamparlo, salvarlo o consegnarlo, e lo dichiara. Un report occupa al massimo 256 KiB, con un massimo di 64 controlli e 512 caratteri in ciascun singolo campo di testo.
Come il report raggiunge la console
L'unica operazione di scrittura del preflight è il report completato, consegnato al servizio chiavi dell'installazione, nexus-keys, affinché il programma di installazione della console possa mostrarlo nella propria pagina di preflight prima che qualcuno abbia reclamato l'installazione. --record decide se effettuare il tentativo:
--record |
Cosa accade |
|---|---|
auto |
Consegna il report solo quando il namespace ha un Deployment nexus-keys |
always |
Insiste; il preflight esce con 2 se non c'è nulla a cui consegnarlo |
never |
Non lo consegna |
Pertanto, un'esecuzione prima della prima installazione non ha nulla a cui effettuare la consegna e mantiene il report sulla vostra workstation. Un'esecuzione dopo l'installazione e prima del reclamo lo registra.
La consegna utilizza il vostro accesso al cluster. nexusctl esegue /app/nexus-keys preflight-record nel container keys di un pod nexus-keys pronto e passa il report sullo standard input. È equivalente a:
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonIl servizio chiavi verifica il report rispetto alle stesse regole applicate da nexusctl e conserva esclusivamente il più recente. Quando viene consegnato, nexusctl stampa un'ulteriore riga che lo conferma e il JSON salvato acquisisce un note che registra la consegna.
Il programma di installazione della console lo legge dalla route pubblica del servizio chiavi GET /v1/installation/preflight. Tale route risponde solo finché l'installazione non viene reclamata: prima che qualsiasi report venga registrato risponde 404 RECORD_NOT_FOUND, e una volta che qualcuno reclama l'installazione risponde ROUTE_NOT_FOUND in modo definitivo, esattamente come fa la route di reclamo. Un report consegnato dopo il reclamo viene rifiutato con INSTALLATION_CLAIMED.
Sulla console, un'esecuzione con errori appare come "Preflight cannot continue": i conteggi dei controlli non superati, degli avvisi e dei controlli superati, seguiti da ogni controllo raggruppato sotto "Must pass" e "Should pass", con quelli non superati per primi e i valori rilevati accanto a ciascuno. Un'esecuzione senza errori non mostra tale pagina; la console passa direttamente al reclamo (capitolo 2.12, La prima esecuzione).
Permessi di accesso necessari per l'esecuzione
Il preflight viene eseguito con la vostra identità, utilizzando il vostro kubeconfig. L'account deve avere accesso in lettura a:
- nodi, per i controlli relativi a versione, stato di prontezza, risorse e grafica;
- classi di archiviazione e classi di ingress;
- Service nel namespace di ingress;
- il Secret TLS nel namespace di installazione, quando viene eseguito il controllo del certificato.
Quando una lettura viene rifiutata, la riga riporta could not read <what> (the cluster refused) e la soluzione indica quale accesso in lettura concedere. Il testo non include mai l'indirizzo del server né il relativo testo di errore, poiché il report potrebbe essere mostrato prima dell'accesso. La consegna richiede inoltre pods/exec sui pod nexus-keys; in sua assenza, auto salva i file e stampa un avviso, e always esce con 2.
Quando preflight stesso non può essere eseguito
Il codice di uscita 2 significa che non è stato generato alcun report. Il messaggio sullo standard error ne indica il motivo:
| Messaggio | Cosa fare |
|---|---|
--context is required: the kube context to check |
Aggiungete --context |
--values is required: the values file the install will use |
Aggiungete --values |
could not read the values file harrow-values.yaml |
Controllate il percorso e i permessi del file |
preflight takes flags only |
Rimuovete l'argomento superfluo |
the report breaks its contract and was not printed, saved or handed over |
Un campo avrebbe contenuto informazioni private; segnalatelo ad Adverant indicando i flag dell'esecuzione |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
Effettuate prima l'installazione, oppure utilizzate --record auto |
could not hand the report to this installation |
Controllate i vostri permessi di accesso per eseguire exec in nexus-keys |
Anche un cluster la cui API non è raggiungibile esce con 2. Correggete il kubeconfig o la rete, quindi ripete l'esecuzione.
Una volta che il preflight termina con 0 failed, passate al capitolo 2.6, Installazione di Community su Kubernetes, per installare Community, oppure al capitolo 2.7, Installazione di Enterprise e applicazione di una licenza, per Enterprise.

