AutentificareProgramați o prezentare

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ă

16 minute de lectură

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

Citeș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.

Înainte de a instala
Înainte de a instala
Verificarea preliminară în terminalul operatorului, cu contoarele alături. Observați că fiecare avertisment are soluția de remediere afișată dedesubt și că rularea precizează clar că nu a modificat nimic în cluster.

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

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

Verificarea preliminară nu poate continua
Verificarea preliminară nu poate continua
Pagina consolei pentru o rulare de verificare preliminară care nu poate continua. Verificările eșuate apar primele, fiecare fiind descrisă în cuvinte împreună cu ceea ce s-a găsit, iar instalarea rămâne blocată până când acestea trec.
Trei coloane. În stânga, „Stația de lucru a operatorului”: o casetă „nexusctl preflight --context --values” având dedesubt două rezultate, „preflight-<time>.txt” și „preflight-<time>.json”. În mijloc, „Instalația, nerevendicată”: o casetă „nexus-keys” cu eticheta „preflight-record, doar cel mai recent raport”. O săgeată de la caseta din stânga către nexus-keys poartă eticheta „pod exec cu propriul dumneavoastră acces la cluster (--record auto sau always)”. În dreapta, „Browser, înainte de autentificare”: o casetă „Programul de instalare al consolei, Verificarea preliminară nu poate continua”. O săgeată de la nexus-keys către aceasta poartă eticheta „GET /v1/installation/preflight”. Sub caseta din mijloc, o notă mică indică „după revendicare: ROUTE_NOT_FOUND”.
Traseul parcurs de un raport de verificare preliminară, de la stația de lucru a operatorului până la browser.

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.