PrijavaRezervirajte predstavitev

Poglavje 2.5

Predhodno preverjanje z orodjem nexusctl

Vsako preverjanje, ki ga izvede `nexusctl preflight`, kaj vsako prebere in kako spodleti, poročilo, ki ga izpiše in shrani, kako to poročilo doseže stran za predhodno preverjanje v konzoli, ter vsa stikala.

To stran je iz angleškega izvirnika prevedla UI. Če je karkoli nejasno, je referenca angleška stran. Preberite to stran v angleščini

16 min branja

Naš prvi predpoletni pregled (preflight) pri Harrow Port Authority ni opravil štirih preverjanj, dve od njih pa bi nas stali precej več kot le eno popoldne. Datoteko z vrednostmi smo začeli ustvarjati s kopiranjem primera iz grafikona (chart), predpoletni pregled pa je zavrnil tako primer imena namestitve kot primer skrbnika (custodian). Nihče nima zasebnega ključa tega skrbnika. Namestitve, ki je zapečatena nanj, po ponovnem zagonu vozlišča ni mogoče nikoli več odpečatiti. Predpoletni pregled je to ujel v nekaj sekundah, še preden je sploh obstajalo kaj, kar bi lahko izgubili.

nexusctl preflight prebere vašo gručo in vašo datoteko z vrednostmi, izpiše ugotovitve, shrani poročilo in v gruči ne spremeni ničesar. Zaženite ga pred vsako namestitvijo in vsako nadgradnjo. To poglavje obravnava vsa preverjanja, ki jih izvede, obliko poročila, kam se poročilo shrani, in zastavice.

Upravljanje

Predpoletni pregled potrebuje dvoje: kontekst kube gruče, v katero boste nameščali, in datoteko z vrednostmi, ki jo bo namestitev uporabila. Najprej napišite datoteko z vrednostmi; poglavje 2.6, Nameščanje izdaje Community v okolju Kubernetes, obravnava vsak ključ. Nato:

nexusctl preflight --context harrow-prod --values harrow-values.yaml

Gručo bere prek knjižnice client-go samo s klici get in list. Če je vaš tls.mode nastavljen na existing, ustvarite imenski prostor nexus in skrivnost (Secret) za Transport Layer Security (TLS), preden ga zaženete (poglavje 2.6, Nameščanje izdaje Community v okolju Kubernetes, 3. korak), sicer bo preverjanje potrdila javilo, da skrivnost manjka.

Zastavica Kaj naredi Privzeto
--context <name> Kontekst kube za preverjanje. Obvezno brez
--values <file> Datoteka z vrednostmi, ki jo bo uporabila namestitev. Obvezno brez
--namespace <name> Kam se namesti Nexus nexus
--release <version> Izdaja, ki se preverja lastna različica priloženega grafikona
--report-dir <dir> Kam se shranita datoteki s poročilom trenutna mapa
--record <mode> auto, always ali never: ali naj se poročilo preda storitvi ključev te namestitve, da ga prikaže njena namestitvena stran auto
--kubeconfig <file> Datoteka kubeconfig za branje KUBECONFIG, nato ~/.kube/config
--ca-bundle <file> Vaša lastna potrdila overitelja potrdil (CA) za verigo, ki ji morajo preverjanja zaupati brez
--single-node Preveri en stroj za namestitev na enem stroju (poglavje 2.8, Namestitve na enem stroju) izklopljeno

Spodnja meja izdaje za Kubernetes ni vpisana v nexusctl. Prebere spodnjo mejo lastnega polja kubeVersion grafikona iz grafikona, ki ga nosi, zato se preverjanje in helm install nikoli ne moreta razhajati.

Kaj izpiše zagon

Tukaj je prvi zagon pri Harrowu, kot se je izpisal:

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

Ko karkoli spodleti, so najprej prikazane napake, nato opozorila in nato uspešno opravljena preverjanja. Vsaka vrstica prikazuje izid, ime preverjanja, kaj je bilo najdeno in kaj potrebuje; vsaka vrstica, ki ni bila uspešna, ima pod seboj vrstico fix. Zadnji dve vrstici sta povzetek in datoteka s poročilom.

Popravili smo vrednosti, dodali oba zapisa za Domain Name System (DNS), ustvarili skrivnost (Secret) in zagon ponovili:

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

Zagon brez napak navede preverjanja pod njihovimi tremi naslovi: Gruča, Omrežje ter Čas in ključi. Opozorila nikoli ne blokirajo. Opozorilo glede grafike smo obdržali namenoma: v tej povezani pilotni gruči je pomočnik pri Harrowu uporabljal gostujoči model z lastnim ključem pristanišča.

Pred namestitvijo
Pred namestitvijo
Predpoletni pregled v operaterjevem terminalu s števci ob strani. Bodite pozorni, da je pod vsakim opozorilom izpisana njegova rešitev in da zagon jasno pove, da v gruči ni spremenil ničesar.

Izhodne kode

Koda Pomen
0 Namestitev se lahko nadaljuje. Opozorila ne blokirajo
1 Namestitev je blokirana: vsaj eno preverjanje ni uspelo
2 Predpoletnega pregleda ni bilo mogoče zagnati: datoteke kubeconfig, konteksta, datoteke z vrednostmi ali aplikacijskega programskega vmesnika (API) gruče ni bilo mogoče prebrati, ali pa je bila zastavica napačna

Skripti naj berejo izhodno kodo, ne besed. Naš zažene predpoletni pregled kot prvi korak vsake nadgradnje in se ustavi ob čemerkoli razen 0.

Zaženite nexusctl tiste izdaje, na katero prehajate, ne tiste, s katero ste namestili. Zahteve izhajajo iz grafikona, ki ga nosi, zato lahko novejša izdaja zviša spodnjo mejo za Kubernetes ali zahteva več pomnilnika, in to ve le njen lastni nexusctl. --release spremeni različico, ki jo imenuje poročilo; ne spremeni pa, pravila katerega grafikona se uporabijo. Pri Harrowu hranimo nexusctl vsake izdaje poleg njenega grafikona v zapisu o spremembah, tako da povrnitev v prejšnje stanje preveri orodje, ki ji ustreza.

Vsako preverjanje

Preverjanj je enajst. Deset od njih ustvari po eno vrstico; preverjanje naslova ustvari eno vrstico na gostitelja, tako da ima polni zagon trinajst vrstic. Devet preverjanj mora uspeti in neuspeh pomeni napako. Dve, grafična vozlišča in potrdilo, bi morali uspeti, neuspeh pa pomeni opozorilo. Zadnji stolpec je besedilo zahteve, ki ga vsaka vrstica prenese v poročilo; CPU v njem pomeni centralno procesno enoto.

ID preverjanja Razdelek Mora uspeti Zahteva, ki jo izpiše
kubernetes-version cluster da Kubernetes 1.33 ali novejši
nodes-ready cluster da Vsako vozlišče pripravljeno
storage-class cluster da Razred shrambe za podatke
resources cluster da Dovolj CPE in pomnilnika za izdajo
graphics-nodes cluster ne Grafična vozlišča
ingress-class network da Vstopni razred (ingress class) za tri naslove
ingress-ports network da Vstopni krmilnik (ingress controller) odprt na vratih 80 in 443
address-console, address-api, address-auth network da Naslov za console, api ali auth je razrešljiv v DNS
certificate network ne Potrdilo veljavno še 30 dni
custodians time-and-keys da Osebe, ki imajo obnovitvene ključe te namestitve
installation-name time-and-keys da Lastno trajno ime te namestitve

kubernetes-version

Prebere različico strežnika API in jo primerja s spodnjo mejo grafikona. Najde na primer 1.33.6+k3s1. Pod 1.33 spodleti z rešitvijo upgrade the cluster to 1.33 or later. Če niza različice nexusctl ne more prebrati, spodleti, namesto da bi ugibal.

nodes-ready

Izpiše vozlišča in prešteje tista, katerih stanje Ready je resnično, kot 3 of 3. Vsako vozlišče, ki ni pripravljeno, je poimenovano, rešitev pa vam naroči, da ga vrnete v stanje Ready in preberete njegova stanja. Gruča brez vozlišč spodleti z namigom, da kontekst morda kaže na napačno gručo.

storage-class

Če vaše vrednosti nastavijo storage.className, preverjanje poišče ta razred in spodleti z <name> does not exist, ko ta manjka. Če ga ne nastavijo, poišče razred, označen kot privzet, in ga javi kot local-path (default). Če privzetega ni, spodleti z none marked default, stolpec s potrebami pa pove, zakaj je to pomembno: the database cannot claim a disk. Če sta kot privzeta označena dva razreda, gruča novemu zahtevku dodeli najnovejšega, zato je javljen ta.

resources

Iz grafikona in vaših vrednosti izračuna, kaj zahteva izdaja, nato pa sešteje dodeljiva jedra centralne procesne enote (CPU) in pomnilnik vsakega vozlišča, ki ima stanje Ready, ni izvzeto (cordoned) in nima oznake (taint) NoSchedule ali NoExecute. Stroki (pods) grafikona nimajo toleranc, zato vozlišče z oznako ne more poganjati teh strokov in se ne šteje. Premajhna gruča spodleti z natančnim primanjkljajem, kot je add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Potrebe se zaokrožijo navzgor, razpoložljivost pa navzdol, tako da vam preverjanje nikoli ne laska.

graphics-nodes

Poišče pripravljeno vozlišče (Ready) z grafično procesno enoto (GPU), ki jo lahko dodeli, nvidia.com/gpu. Če ga ni, opozori: the assistant will need a hosted model. Predpoletni pregled to obravnava kot nasvet in zaradi tega nikoli ne blokira, saj lahko pomočnik namesto tega odgovarja prek gostujočega modela umetne inteligence (UI). Poglavje 2.14, Ponudniki in modeli UI, obravnava obe poti.

ingress-class

Če je ingress.className nastavljen, preverjanje poišče ta razred. Če ni, poišče natanko en razred, označen kot privzet. Tudi dva razreda, označena kot privzeta, pomenita napako, saj strežnik API v tem primeru zavrne Ingress brez razreda. Preverjanje se preskoči in njegova vrstica izpusti, ko je ingress.enabled nastavljen na false.

ingress-ports

V imenskem prostoru, ki ga imenuje networkPolicy.ingressNamespace (privzeto kube-system, kjer k3s poganja Traefik), poišče eno storitev (Service) tipa LoadBalancer ali NodePort, ki izpostavlja tako vrata 80 kot 443. Omrežni pravilnik grafikona dovoljuje dostop do treh javnih storitev samo temu imenskemu prostoru, zato vstopni krmilnik (ingress controller) kjerkoli drugje ne bi mogel streči sistemu Nexus, tudi če bi poslušal. Rešitev imenuje oba izhoda: izpostavite krmilnik tam ali nastavite networkPolicy.ingressNamespace na mesto, kjer teče. Preskočeno, ko je ingress.enabled nastavljen na false.

address

Poišče hosts.console, hosts.api in hosts.auth z vaše delovne postaje, po pet sekund za vsakega, in izpiše eno vrstico na gostitelja. Gostitelj brez zapisa spodleti z <host> → no record. Nenastavljen gostitelj spodleti z hosts.<key> is not set. Ko ima ime več naslovov, vrstica prikaže prvega, IPv4 pred IPv6, in koliko jih je še.

certificate

Teče samo, ko je tls.mode nastavljen na existing in tls.existingSecret imenuje skrivnost (Secret); pri cert-manager ali none ni nobenega vašega potrdila za branje in vrstica je izpuščena. Prebere tls.crt iz skrivnosti v namestitvenem imenskem prostoru in ničesar drugega. Potrdilo, veljavno 30 dni ali več, uspe kot ends 3 Nov 2027. Tisto, ki poteče prej, opozori z ends in 9 days; tisto, ki je že poteklo, opozori z ended 4 days ago. Manjkajoča skrivnost ali skrivnost brez potrdila v njej opozori z rešitvijo.

custodians

Prebere keys.custody.recipients. Če ni nobenega, spodleti s kodo KEYS_CUSTODIAN_MISSING. Če je katerikoli prejemnik primer skrbnika iz lastnih datotek z vrednostmi grafikona, spodleti z KEYS_CUSTODIAN_EXAMPLE, saj tega ključa nima nihče in bi bili obnovitveni ključi namestitve zapečateni nikomur. Ob uspehu se izpiše število, na primer 3 custodians.

installation-name

Prebere keys.installationName. Če ni nastavljeno, spodleti z INSTALLATION_NAME_MISSING. Če je nastavljeno na primer imena iz datotek z vrednostmi grafikona, spodleti z INSTALLATION_NAME_EXAMPLE. Ob uspehu se izpiše ime. Stolpec s potrebami pove, zakaj je to preverjanje pomembnejše od večine: the first key-store bootstrap mints the installation identity under it, permanently.

Zadnji dve preverjanji javita natanko tisti kodi, s katerima sam grafikon zavrne namestitev. Predpoletni pregled vam to le pove prej, preden Helm karkoli ustvari.

Datoteke poročila

Vsak zagon shrani dve datoteki v --report-dir, poimenovani po času zagona: preflight-2026-11-12-0902.txt, vrstice, kot so bile izpisane, brez barvnih kod, in preflight-2026-11-12-0902.json, isti zagon v nespremenljivi obliki, ki jo lahko prebere program. Izpis v terminalu in shranjene vrstice izvirajo iz istega seznama, zato se nikoli ne razlikujejo.

Poročilo JSON sledi shemi nexus.preflight/v1:

Polje Kaj vsebuje
schema Natanko nexus.preflight/v1
tool Objekt: name (nexusctl) in version
release Preverjena izdaja
ran_at Kdaj se je zagnal, v univerzalnem koordiniranem času (UTC)
context Ime konteksta kube
values Samo osnovno ime datoteke z vrednostmi
read_only Vedno true
checks En vnos na vrstico: id, section, name, requirement, must_pass, outcome (pass, warn ali fail), found, needs, fix in ob neuspehu s strojnim vzrokom še code
counts passed, warnings in failed
can_install true, ko ni nič spodletelo
report_file Ime datoteke .txt
transcript Objekt: title (nexusctl preflight) in lines, vsaka vrstica s svojim kind (prompt, ok, warn, bad, note, out ali blank), svojim text in at ter včasih marks

Poročilo je zasnovano tako, da se prikaže, preden se kdorkoli prijavi, zato ne vsebuje uporabniškega imena, imena gostitelja delovne postaje, poti do datoteke, žetona in ničesar iz vaše datoteke kubeconfig. values je osnovno ime in context je ime konteksta. Če bi poročilo zagona kršilo katerokoli od teh pravil, ga nexusctl zavrne izpisati, shraniti ali predati in to tudi sporoči. Poročilo je veliko največ 256 KiB, z največ 64 preverjanji in 512 znaki v kateremkoli posameznem besedilnem polju.

Kako poročilo doseže konzolo

Edino pisanje predpoletnega pregleda je končano poročilo, predano storitvi ključev namestitve, nexus-keys, tako da ga lahko namestitveni program konzole prikaže na svoji strani predpoletnega pregleda, preden kdorkoli prevzame namestitev. --record odloča, ali naj poskusi:

--record Kaj se zgodi
auto Preda poročilo samo, ko ima imenski prostor razmestitev (Deployment) nexus-keys
always Vztraja; predpoletni pregled se konča z 2, če poročila nima čemu predati
never Ne preda ga

Zagon pred prvo namestitvijo torej nima čemu predati poročila in ga obdrži na vaši delovni postaji. Zagon po namestitvi in pred prevzemom pa ga zabeleži.

Predaja uporabi vaš lastni dostop do gruče. nexusctl zažene /app/nexus-keys preflight-record v vsebniku keys pripravljenega stroka (pod) nexus-keys in poda poročilo na standardni vhod. To je enako kot:

kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.json

Storitev ključev preveri poročilo po istih pravilih, kot jih uporablja nexusctl, in obdrži samo najnovejšega. Ko je predano, nexusctl izpiše še eno vrstico, ki to sporoča, shranjeni JSON pa pridobi note, ki zabeleži predajo.

Namestitveni program konzole ga prebere z javne poti storitve ključev GET /v1/installation/preflight. Ta pot odgovarja le, dokler je namestitev neprevzeta: preden je zabeleženo kakršnokoli poročilo, odgovarja z 404 RECORD_NOT_FOUND, ko pa nekdo namestitev prevzame, za stalno odgovarja z ROUTE_NOT_FOUND, natanko tako kot pot za prevzem. Poročilo, predano po prevzemu, je zavrnjeno z INSTALLATION_CLAIMED.

V konzoli se zagon z napakami prikaže kot »Preflight cannot continue« (Predpoletni pregled se ne more nadaljevati): število neuspelih, opozoril in uspelih, nato pa vsako preverjanje, združeno pod »Must pass« (Mora uspeti) in »Should pass« (Bi moralo uspeti), pri čemer so tista, ki niso uspela, na prvem mestu, poleg vsakega pa so najdene besede. Zagon brez napak te strani ne dobi; konzola nadaljuje naravnost na prevzem (poglavje 2.12, Prvi zagon).

Predpoletni pregled se ne more nadaljevati
Predpoletni pregled se ne more nadaljevati
Stran konzole za zagon predpoletnega pregleda, ki se ne more nadaljevati. Neuspela preverjanja so na prvem mestu, vsako je ubesedeno s tem, kar je bilo najdeno, namestitev pa ostane blokirana, dokler ne uspejo.
Trije stolpci. Levo, »Operaterjeva delovna postaja«: okvir »nexusctl preflight --context --values« z dvema izhodoma pod njim, »preflight-<time>.txt« in »preflight-<time>.json«. Na sredini, »Namestitev, neprevzeta«: okvir »nexus-keys« z oznako »preflight-record, samo najnovejše poročilo«. Puščica iz levega okvira do nexus-keys je označena z »izvajanje v stroku (pod exec) z vašim lastnim dostopom do gruče (--record auto ali always)«. Desno, »Brskalnik, pred prijavo«: okvir »Namestitveni program konzole, Predpoletni pregled se ne more nadaljevati«. Puščica iz nexus-keys do njega je označena z »GET /v1/installation/preflight«. Pod srednjim okvirom je majhen pripis »po prevzemu: ROUTE_NOT_FOUND«.
Kam gre eno poročilo predpoletnega pregleda, od operaterjeve delovne postaje do brskalnika.

Dostop, ki ga potrebuje zagon

Predpoletni pregled teče pod vašim imenom, z vašo datoteko kubeconfig. Račun mora imeti pravice za branje:

  • vozlišč, za preverjanje različice, pripravljenosti, virov in grafike;
  • razredov shrambe in vstopnih razredov (ingress classes);
  • storitev (Services) v vstopnem imenskem prostoru (ingress namespace);
  • skrivnosti (Secret) TLS v namestitvenem imenskem prostoru, ko teče preverjanje potrdila.

Ko je branje zavrnjeno, vrstica javi could not read <what> (the cluster refused), rešitev pa pove, kateri bralni dostop je treba dodeliti. Besede nikoli ne vključujejo naslova strežnika ali njegovega lastnega besedila napake, ker se poročilo lahko prikaže pred prijavo. Predaja potrebuje tudi pods/exec na strokih nexus-keys; brez tega auto shrani datoteki in izpiše opozorilo, always pa se konča z 2.

Ko se samo predhodno preverjanje ne more zagnati

Izhodna koda 2 pomeni, da poročilo ni bilo ustvarjeno. Sporočilo na standardnem izhodu za napake pove, zakaj:

Sporočilo Kaj storiti
--context is required: the kube context to check Dodajte --context
--values is required: the values file the install will use Dodajte --values
could not read the values file harrow-values.yaml Preverite pot in dovoljenja datoteke
preflight takes flags only Odstranite odvečni argument
the report breaks its contract and was not printed, saved or handed over Polje bi vsebovalo nekaj zasebnega; sporočite to podjetju Adverant skupaj z zastavicami zagona
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to Najprej namestite ali uporabite --record auto
could not hand the report to this installation Preverite svoj dostop za izvajanje (exec) v nexus-keys

Gruča, katere API ni dosegljiv, se prav tako konča z 2. Popravite datoteko kubeconfig ali omrežje in zagon ponovite.

Ko se predpoletni pregled konča z 0 failed, nadaljujte s poglavjem 2.6, Nameščanje izdaje Community v okolju Kubernetes, za namestitev izdaje Community, ali s poglavjem 2.7, Nameščanje izdaje Enterprise in uveljavljanje licence, za izdajo Enterprise.