AccediPrenota un briefing

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

16 minuti di lettura

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.yaml

Legge 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.

Prima dell'installazione
Prima dell'installazione
Il preflight nel terminale dell'operatore, con i conteggi accanto. Notate che sotto ogni avviso è stampata la relativa soluzione e che l'esecuzione dichiara chiaramente di non aver modificato nulla sul cluster.

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.json

Il 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).

Preflight cannot continue
Preflight cannot continue
La pagina della console per un'esecuzione di preflight che non può proseguire. I controlli non superati compaiono per primi, ciascuno descritto a parole insieme a ciò che è stato rilevato, e l'installazione rimane bloccata finché non vengono superati.
Tre colonne. A sinistra, "Workstation dell'operatore": un riquadro "nexusctl preflight --context --values" con due output sottostanti, "preflight-<time>.txt" e "preflight-<time>.json". Al centro, "L'installazione, non reclamata": un riquadro "nexus-keys" con l'etichetta "preflight-record, solo il report più recente". Una freccia dal riquadro di sinistra a nexus-keys riporta l'etichetta "pod exec con il vostro accesso al cluster (--record auto o always)". A destra, "Browser, prima dell'accesso": un riquadro "Programma di installazione della console, Preflight cannot continue". Una freccia da nexus-keys verso di esso riporta l'etichetta "GET /v1/installation/preflight". Sotto il riquadro centrale, una piccola nota indica "dopo il reclamo: ROUTE_NOT_FOUND".
Il percorso di un report di preflight, dalla workstation dell'operatore al browser.

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.