Različica 1.0.0-alpha.1najnovejša
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

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.yamlGruč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.
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.jsonStoritev 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).
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.

