Versiune 1.0.0-alpha.1cea mai recentă
Capitolul 2.5
Verificarea prealabilă cu nexusctl
Fiecare verificare efectuată de `nexusctl preflight`, ce citește fiecare și cum eșuează, raportul pe care îl afișează și îl salvează, cum ajunge acel raport în pagina de verificare prealabilă a consolei și fiecare indicator (flag).
Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

Prima noastră verificare preliminară (preflight) la Harrow Port Authority a eșuat la patru teste, iar două dintre acestea ne-ar fi costat mult mai mult decât o simplă după-amiază. Începuserăm fișierul de valori prin copierea exemplului din chart, iar verificarea preliminară a refuzat atât numele instalației din exemplu, cât și custodele din exemplu. Nimeni nu deține cheia privată a acelui custode. O instalație sigilată pe numele acestuia nu mai poate fi niciodată desigilată după repornirea unui nod. Verificarea preliminară a depistat acest lucru în câteva secunde, înainte să existe ceva ce am fi putut pierde.
nexusctl preflight citește clusterul și fișierul dumneavoastră de valori, afișează ce a găsit, salvează un raport și nu modifică nimic în cluster. Rulați-l înainte de fiecare instalare și de fiecare actualizare. Acest capitol prezintă fiecare verificare efectuată, formatul raportului, locația în care este salvat raportul și opțiunile (flags).
Operarea
Verificarea preliminară are nevoie de două elemente: contextul kube al clusterului pe care veți instala și fișierul de valori pe care îl va folosi instalarea. Scrieți mai întâi fișierul de valori; capitolul 2.6, Instalarea ediției Community pe Kubernetes, parcurge fiecare cheie. Apoi:
nexusctl preflight --context harrow-prod --values harrow-values.yamlCitește clusterul prin client-go folosind exclusiv apeluri de tip get și list. Dacă tls.mode este existing, creați spațiul de nume (namespace) nexus și obiectul Secret pentru Transport Layer Security (TLS) înainte de a rula comanda (capitolul 2.6, Instalarea ediției Community pe Kubernetes, pasul 3); în caz contrar, verificarea certificatului va raporta că obiectul Secret lipsește.
| Opțiune | Ce face | Valoare implicită |
|---|---|---|
--context <name> |
Contextul kube de verificat. Obligatoriu | niciuna |
--values <file> |
Fișierul de valori pe care îl va folosi instalarea. Obligatoriu | niciuna |
--namespace <name> |
Unde se instalează Nexus | nexus |
--release <version> |
Versiunea (release) verificată | versiunea proprie a chart-ului inclus |
--report-dir <dir> |
Unde sunt salvate cele două fișiere de raport | dosarul curent |
--record <mode> |
auto, always sau never: dacă raportul trebuie predat serviciului de chei al acestei instalații, astfel încât pagina sa de instalare să îl afișeze |
auto |
--kubeconfig <file> |
Fișierul kubeconfig de citit | KUBECONFIG, apoi ~/.kube/config |
--ca-bundle <file> |
Propriile dumneavoastră certificate ale autorității de certificare (CA), pentru un lanț în care verificările ar trebui să aibă încredere | niciuna |
--single-node |
Verifică o singură mașină pentru o instalare pe o singură mașină (capitolul 2.8, Instalări pe o singură mașină) | dezactivat |
Versiunea minimă de Kubernetes pentru această lansare nu este scrisă direct în nexusctl. Aceasta citește limita inferioară din kubeVersion-ul propriu al chart-ului pe care îl conține, astfel încât verificarea și helm install nu pot fi niciodată în contradicție.
Ce afișează o rulare
Iată prima rulare de la Harrow, exact așa cum a fost afișată:
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
Când ceva eșuează, erorile sunt afișate primele, urmate de avertismente, iar apoi de verificările trecute cu succes. Fiecare rând indică rezultatul, numele verificării, ce s-a găsit și ce este necesar; fiecare rând care nu a trecut testul are o linie fix dedesubt. Ultimele două linii reprezintă rezumatul și fișierul de raport.
Am corectat valorile, am adăugat cele două înregistrări Domain Name System (DNS), am creat obiectul Secret și am rulat din nou comanda:
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
O rulare fără erori listează verificările sub cele trei categorii ale lor: Cluster, Rețea (Network) și Timp și chei (Time and keys). Avertismentele nu blochează niciodată procesul. Am păstrat intenționat avertismentul legat de placa grafică: pe acest cluster pilot conectat, asistentul de la Harrow a folosit un model găzduit, cu cheia proprie a portului.
Coduri de ieșire
| Cod | Semnificație |
|---|---|
0 |
Instalarea poate continua. Avertismentele nu blochează |
1 |
Instalarea este blocată: cel puțin o verificare a eșuat |
2 |
Verificarea preliminară nu a putut rula: fișierul kubeconfig, contextul, fișierul de valori sau interfața de programare a aplicațiilor (API) a clusterului nu au putut fi citite, ori o opțiune a fost greșită |
Scripturile ar trebui să citească codul de ieșire (exit code), nu textul. Al nostru rulează verificarea preliminară ca prim pas al fiecărei actualizări și se oprește la orice alt rezultat în afară de 0.
Rulați nexusctl aferent versiunii la care treceți, nu pe cel cu care ați instalat inițial. Cerințele provin din chart-ul pe care îl conține, astfel încât o versiune mai nouă poate ridica pragul minim pentru Kubernetes sau poate solicita mai multă memorie, iar doar propriul său nexusctl cunoaște aceste detalii. --release modifică versiunea menționată în raport, dar nu schimbă regulile chart-ului care sunt aplicate. La Harrow, păstrăm nexusctl-ul fiecărei versiuni lângă chart-ul său în jurnalul de modificări, astfel încât o revenire la versiunea anterioară (rollback) este verificată de instrumentul care îi corespunde.
Fiecare verificare
Există unsprezece verificări. Zece dintre ele produc câte un rând fiecare; verificarea adreselor produce câte un rând pentru fiecare gazdă (host), astfel încât o rulare completă are treisprezece rânduri. Nouă verificări trebuie să treacă obligatoriu, iar o neconformitate reprezintă un eșec. Două verificări, nodurile grafice și certificatul, este recomandat să treacă, iar o neconformitate reprezintă un avertisment. Ultima coloană conține textul cerinței pe care fiecare rând îl transmite în raport; în cadrul acesteia, CPU reprezintă unitatea centrală de procesare.
| ID verificare | Secțiune | Obligatorie | Cerința afișată |
|---|---|---|---|
kubernetes-version |
cluster | yes | Kubernetes 1.33 sau o versiune ulterioară |
nodes-ready |
cluster | yes | Fiecare nod este pregătit (Ready) |
storage-class |
cluster | yes | O clasă de stocare (storage class) pentru date |
resources |
cluster | yes | Suficient CPU și memorie pentru această versiune |
graphics-nodes |
cluster | no | Noduri grafice |
ingress-class |
network | yes | O clasă de ingress (ingress class) pentru cele trei adrese |
ingress-ports |
network | yes | Controllerul de ingress deschis pe porturile 80 și 443 |
address-console, address-api, address-auth |
network | yes | Adresa console, api sau auth se rezolvă în DNS |
certificate |
network | no | Certificat valabil pentru încă 30 de zile |
custodians |
time-and-keys | yes | Persoanele care dețin cheile de recuperare ale acestei instalații |
installation-name |
time-and-keys | yes | Numele permanent propriu al acestei instalații |
kubernetes-version
Citește versiunea serverului API și o compară cu pragul minim al chart-ului. Găsește, de exemplu, 1.33.6+k3s1. Sub 1.33, eșuează indicând soluția upgrade the cluster to 1.33 or later. Dacă șirul versiunii nu poate fi citit de nexusctl, verificarea eșuează în loc să presupună.
nodes-ready
Listează nodurile și le numără pe cele a căror condiție Ready este adevărată, sub forma 3 of 3. Orice nod care nu este pregătit este nominalizat, iar soluția vă indică să îl readuceți la starea Ready și să îi citiți condițiile. Un cluster fără niciun nod eșuează cu un indiciu că este posibil ca respectivul context să indice spre un cluster greșit.
storage-class
Dacă valorile dumneavoastră setează storage.className, verificarea caută clasa respectivă și eșuează cu <name> does not exist atunci când aceasta lipsește. Dacă nu o setează, caută o clasă marcată ca implicită (default) și o raportează ca local-path (default). Fără o clasă implicită, eșuează cu none marked default, iar coloana de cerințe explică de ce contează acest lucru: the database cannot claim a disk. Dacă două clase sunt marcate ca implicite, clusterul îi atribuie unei cereri noi pe cea mai recentă, prin urmare aceasta este cea raportată.
resources
Calculează resursele solicitate de versiune pe baza chart-ului și a valorilor dumneavoastră, apoi însumează nucleele alocabile ale unității centrale de procesare (CPU) și memoria fiecărui nod care este Ready, nu este izolat (cordoned) și nu poartă niciun marcaj (taint) NoSchedule sau NoExecute. Pod-urile chart-ului nu au toleranțe (tolerations), astfel încât un nod cu taint nu le poate rula și nu este luat în calcul. Un cluster cu resurse insuficiente eșuează indicând deficitul exact, cum ar fi add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Cerințele sunt rotunjite în sus, iar resursele disponibile sunt rotunjite în jos, astfel încât verificarea nu supraestimează niciodată capacitatea.
graphics-nodes
Caută un nod Ready cu o unitate de procesare grafică (GPU) pe care o poate aloca, nvidia.com/gpu. Dacă nu găsește niciuna, emite un avertisment: the assistant will need a hosted model. Verificarea preliminară tratează acest aspect ca pe o recomandare și nu blochează niciodată instalarea din această cauză, deoarece asistentul poate răspunde în schimb prin intermediul unui model găzduit de inteligență artificială (IA). Capitolul 2.14, Furnizori și modele de IA, acoperă ambele variante.
ingress-class
Dacă ingress.className este setat, verificarea caută clasa respectivă. În caz contrar, caută exact o singură clasă marcată ca implicită. Existența a două clase marcate ca implicite duce, de asemenea, la eșec, deoarece serverul API refuză în acest caz un Ingress fără clasă specificată. Verificarea este omisă, iar rândul său este exclus, atunci când ingress.enabled este false.
ingress-ports
Caută în spațiul de nume indicat de networkPolicy.ingressNamespace (în mod implicit kube-system, unde k3s rulează Traefik) un serviciu de tip LoadBalancer sau NodePort care expune atât portul 80, cât și 443. Politica de rețea a chart-ului permite doar acelui spațiu de nume să acceseze cele trei servicii publice, astfel încât un controller de ingress aflat oriunde altundeva nu ar putea deservi Nexus, chiar dacă ar asculta conexiuni. Soluția indică ambele variante de rezolvare: expuneți controllerul acolo sau setați networkPolicy.ingressNamespace la locația în care acesta rulează. Verificarea este omisă când ingress.enabled este false.
address
Caută hosts.console, hosts.api și hosts.auth de pe stația dumneavoastră de lucru, alocând câte cinci secunde pentru fiecare, și afișează câte un rând pentru fiecare gazdă. O gazdă fără înregistrare eșuează cu <host> → no record. O gazdă nesetată eșuează cu hosts.<key> is not set. Când un nume are mai multe adrese, rândul o afișează pe prima, acordând prioritate IPv4 față de IPv6, și indică încă câte adrese mai există.
certificate
Rulează doar când tls.mode este existing și tls.existingSecret numește un Secret; cu cert-manager sau none nu există niciun certificat propriu de citit, iar rândul este exclus. Citește tls.crt din obiectul Secret aflat în spațiul de nume al instalării și nimic altceva. Un certificat valabil pentru 30 de zile sau mai mult trece verificarea ca ends 3 Nov 2027. Unul care expiră mai curând emite avertismentul ends in 9 days; unul deja expirat emite avertismentul ended 4 days ago. Un Secret lipsă sau unul care nu conține niciun certificat emite un avertisment însoțit de soluție.
custodians
Citește keys.custody.recipients. Dacă nu există niciunul, eșuează cu codul KEYS_CUSTODIAN_MISSING. Dacă vreun destinatar este custodele din exemplu, provenit din fișierele de valori proprii ale chart-ului, eșuează cu KEYS_CUSTODIAN_EXAMPLE, deoarece nimeni nu deține acea cheie, iar cheile de recuperare ale instalației ar fi sigilate pentru nimeni. O verificare trecută cu succes afișează numărul acestora, cum ar fi 3 custodians.
installation-name
Citește keys.installationName. Dacă nu este setat, eșuează cu INSTALLATION_NAME_MISSING. Dacă este setat la numele din exemplu din fișierele de valori ale chart-ului, eșuează cu INSTALLATION_NAME_EXAMPLE. O verificare trecută cu succes afișează numele. Coloana de cerințe explică de ce această verificare contează mai mult decât majoritatea: the first key-store bootstrap mints the installation identity under it, permanently.
Ultimele două verificări raportează exact codurile cu care chart-ul însuși refuză o instalare. Verificarea preliminară doar vă informează în prealabil, înainte ca Helm să fi creat ceva.
Fișierele de raport
Fiecare rulare salvează două fișiere în --report-dir, denumite după momentul în care a avut loc rularea: preflight-2026-11-12-0902.txt, liniile exact așa cum au fost afișate, fără coduri de culoare, și preflight-2026-11-12-0902.json, aceeași rulare într-un format fix pe care îl poate citi un program. Rezultatul din terminal și liniile salvate provin din aceeași listă, astfel încât nu diferă niciodată.
Raportul JSON respectă schema nexus.preflight/v1:
| Câmp | Ce conține |
|---|---|
schema |
Exact nexus.preflight/v1 |
tool |
Un obiect: name (nexusctl) și version |
release |
Versiunea verificată |
ran_at |
Momentul în care a rulat, în timpul universal coordonat (UTC) |
context |
Numele contextului kube |
values |
Doar numele de bază al fișierului de valori |
read_only |
Întotdeauna true |
checks |
Câte o intrare pentru fiecare rând: id, section, name, requirement, must_pass, outcome (pass, warn sau fail), found, needs, fix, iar în caz de neconformitate cu o cauză identificabilă automat, code |
counts |
passed, warnings și failed |
can_install |
true când nimic nu a eșuat |
report_file |
Numele fișierului .txt |
transcript |
Un obiect: title (nexusctl preflight) și lines, fiecare linie cu kind-ul său (prompt, ok, warn, bad, note, out sau blank), text-ul și at-ul său, și uneori marks |
Raportul este conceput pentru a fi afișat înainte ca cineva să se autentifice, prin urmare nu conține niciun nume de utilizator, niciun nume de gazdă al stației de lucru, nicio cale de fișier, niciun token și nimic din fișierul dumneavoastră kubeconfig. values este un nume de bază, iar context este numele contextului. Dacă raportul unei rulări ar încălca oricare dintre aceste reguli, nexusctl refuză să îl afișeze, să îl salveze sau să îl predea, și precizează acest lucru. Un raport are cel mult 256 KiB, cu maximum 64 de verificări și 512 caractere în orice câmp individual de text.
Cum ajunge raportul în consolă
Singura operațiune de scriere a verificării preliminare este raportul finalizat, predat serviciului de chei al instalației, nexus-keys, astfel încât programul de instalare al consolei să îl poată afișa pe pagina sa de verificare preliminară înainte ca cineva să fi revendicat instalația. --record decide dacă să încerce predarea:
--record |
Ce se întâmplă |
|---|---|
auto |
Predă raportul doar atunci când spațiul de nume are un Deployment nexus-keys |
always |
Insistă; verificarea preliminară iese cu codul 2 dacă nu are cui să îl predea |
never |
Nu îl predă |
Astfel, o rulare înainte de prima instalare nu are cui să predea raportul și îl păstrează pe stația dumneavoastră de lucru. O rulare după instalare și înainte de revendicare îl înregistrează.
Predarea folosește propriul dumneavoastră acces la cluster. nexusctl rulează /app/nexus-keys preflight-record în containerul keys al unui pod nexus-keys pregătit (ready) și transmite raportul prin intrarea standard (standard input). Este echivalent cu:
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonServiciul de chei verifică raportul în raport cu aceleași reguli pe care le aplică nexusctl și îl păstrează doar pe cel mai recent. Când este predat, nexusctl afișează încă o linie care confirmă acest lucru, iar fișierul JSON salvat primește o intrare note care înregistrează predarea.
Programul de instalare al consolei îl citește de pe ruta publică GET /v1/installation/preflight a serviciului de chei. Această rută răspunde doar cât timp instalația este nerevendicată: înainte de înregistrarea oricărui raport, răspunde cu 404 RECORD_NOT_FOUND, iar odată ce cineva revendică instalația, răspunde definitiv cu ROUTE_NOT_FOUND, exact așa cum procedează ruta de revendicare. Un raport predat după revendicare este refuzat cu INSTALLATION_CLAIMED.
În consolă, o rulare cu erori apare ca „Preflight cannot continue” (Verificarea preliminară nu poate continua): numărul de verificări eșuate, avertismente și verificări trecute, urmate de fiecare verificare grupată sub „Must pass” (Obligatorii) și „Should pass” (Recomandate), având primele verificările care nu au trecut și valorile găsite alături de fiecare. O rulare fără erori nu afișează acea pagină; consola trece direct la revendicare (capitolul 2.12, Prima rulare).
Accesul necesar pentru rulare
Verificarea preliminară rulează în numele dumneavoastră, folosind fișierul dumneavoastră kubeconfig. Contul are nevoie de drepturi de citire pentru:
- noduri, pentru verificările privind versiunea, starea de pregătire, resursele și plăcile grafice;
- clasele de stocare și clasele de ingress;
- serviciile (Services) din spațiul de nume de ingress;
- obiectul Secret TLS din spațiul de nume al instalării, atunci când rulează verificarea certificatului.
Când o citire este refuzată, rândul afișează could not read <what> (the cluster refused), iar soluția indică ce drepturi de citire trebuie acordate. Textul nu include niciodată adresa serverului sau propriul său mesaj de eroare, deoarece raportul poate fi afișat înainte de autentificare. Predarea necesită, de asemenea, permisiunea pods/exec pe pod-urile nexus-keys; fără aceasta, auto salvează fișierele și afișează un avertisment, iar always iese cu codul 2.
Când verificarea prealabilă în sine nu poate rula
Codul de ieșire 2 înseamnă că nu a fost generat niciun raport. Mesajul de la ieșirea standard de eroare (standard error) explică motivul:
| Mesaj | Ce trebuie să faceți |
|---|---|
--context is required: the kube context to check |
Adăugați --context |
--values is required: the values file the install will use |
Adăugați --values |
could not read the values file harrow-values.yaml |
Verificați calea și permisiunile fișierului |
preflight takes flags only |
Eliminați argumentul în plus |
the report breaks its contract and was not printed, saved or handed over |
Un câmp ar fi conținut informații private; raportați acest lucru către Adverant împreună cu opțiunile rulării |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
Instalați mai întâi sau folosiți --record auto |
could not hand the report to this installation |
Verificați-vă accesul de a executa comenzi (exec) în nexus-keys |
Un cluster al cărui API nu poate fi contactat iese, de asemenea, cu codul 2. Corectați fișierul kubeconfig sau rețeaua și rulați din nou comanda.
Odată ce verificarea preliminară se încheie cu 0 failed, treceți la capitolul 2.6, Instalarea ediției Community pe Kubernetes, pentru a instala ediția Community, sau la capitolul 2.7, Instalarea ediției Enterprise și aplicarea unei licențe, pentru ediția Enterprise.

