Versjon 1.0.0-alpha.1nyeste
Kapittel 2.5
Forhåndskontroll med nexusctl
Hver kontroll `nexusctl preflight` utfører, hva hver enkelt leser og hvordan den feiler, rapporten den skriver ut og lagrer, hvordan denne rapporten når forhåndskontrollsiden i konsollen, og hvert flagg.
Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

Vår første forhåndssjekk hos Harrow Port Authority feilet på fire sjekker, og to av dem ville ha kostet oss langt mer enn en ettermiddag. Vi hadde startet verdifilen ved å kopiere chartets eksempel, og forhåndssjekken avviste både det eksempelvise installasjonsnavnet og eksempel-forvalteren. Ingen sitter på den forvalterens private nøkkel. En installasjon som er forseglet til den, kan aldri låses opp etter en omstart av en node. Forhåndssjekken fanget opp dette på noen få sekunder, før det fantes noe å miste.
nexusctl preflight leser klyngen din og verdifilen din, skriver ut hva den fant, lagrer en rapport og endrer ingenting i klyngen. Kjør den før hver installasjon og hver oppgradering. Dette kapittelet dekker hver sjekk den gjør, rapportformatet, hvor rapporten havner, og flaggene.
Drift
Forhåndssjekken trenger to ting: kube-konteksten til klyngen du skal installere på, og verdifilen som installasjonen skal bruke. Skriv verdifilen først; kapittel 2.6, Installere Community på Kubernetes, går gjennom hver nøkkel. Deretter:
nexusctl preflight --context harrow-prod --values harrow-values.yamlDen leser klyngen gjennom client-go med kun get- og list-kall. Hvis din tls.mode er existing, må du opprette navnerommet nexus og Transport Layer Security (TLS)-Secret-objektet før du kjører den (kapittel 2.6, Installere Community på Kubernetes, trinn 3), ellers rapporterer sertifikatsjekken at Secret-objektet mangler.
| Flagg | Hva den gjør | Standard |
|---|---|---|
--context <name> |
Kube-konteksten som skal sjekkes. Påkrevd | ingen |
--values <file> |
Verdifilen som installasjonen skal bruke. Påkrevd | ingen |
--namespace <name> |
Hvor Nexus installeres | nexus |
--release <version> |
Utgivelsen som sjekkes | det medfølgende chartets egen versjon |
--report-dir <dir> |
Hvor de to rapportfilene lagres | den gjeldende mappen |
--record <mode> |
auto, always eller never: hvorvidt rapporten skal overleveres til denne installasjonens nøkkeltjeneste, slik at installasjonssiden dens viser den |
auto |
--kubeconfig <file> |
Kubeconfig-filen som skal leses | KUBECONFIG, deretter ~/.kube/config |
--ca-bundle <file> |
Dine egne sertifikater fra en sertifiseringsinstans (CA), for en kjede som sjekkene skal stole på | ingen |
--single-node |
Sjekk én maskin for en enkeltmaskin-installasjon (kapittel 2.8, Enkeltmaskin-installasjoner) | av |
Utgivelsens nedre grense for Kubernetes er ikke skrevet inn i nexusctl. Den leser den nedre grensen for chartets egen kubeVersion fra chartet den har med seg, slik at sjekken og helm install aldri kan være uenige.
Hva en kjøring skriver ut
Her er Harrows første kjøring, slik den ble skrevet ut:
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
Når noe feiler, kommer feilene først, deretter advarslene, og til slutt det som er godkjent. Hver rad viser utfallet, sjekkens navn, hva som ble funnet, og hva den krever; hver rad som ikke ble godkjent, har en fix-linje under seg. De to siste linjene er sammendraget og rapportfilen.
Vi rettet verdiene, la til de to Domain Name System (DNS)-oppføringene, opprettet Secret-objektet og kjørte den på nytt:
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
En kjøring uten feil lister opp sjekkene under de tre overskriftene deres: Klynge, Nettverk, og Tid og nøkler. Advarsler blokkerer aldri. Vi beholdt grafikkadvarselen med vilje: på denne tilkoblede pilotklyngen brukte Harrows assistent en vertsbasert modell med havnens egen nøkkel.
Avslutningskoder
| Kode | Betydning |
|---|---|
0 |
Installasjonen kan fortsette. Advarsler blokkerer ikke |
1 |
Installasjonen er blokkert: minst én sjekk feilet |
2 |
Forhåndssjekken kunne ikke kjøre: kubeconfig-filen, konteksten, verdifilen eller klyngens applikasjonsprogrammeringsgrensesnitt (API) kunne ikke leses, eller et flagg var feil |
Skript bør lese avslutningskoden, ikke ordene. Vårt kjører forhåndssjekken som det første trinnet i hver oppgradering og stopper ved alt annet enn 0.
Kjør nexusctl fra utgivelsen du går over til, ikke den du installerte med. Kravene kommer fra chartet den har med seg, så en nyere utgivelse kan heve den nedre grensen for Kubernetes eller be om mer minne, og bare dens egen nexusctl vet dette. --release endrer versjonen som rapporten oppgir; det endrer ikke hvilket charts regler som brukes. Hos Harrow oppbevarer vi hver utgivelses nexusctl ved siden av chartet i endringsloggen, slik at en tilbakerulling sjekkes av verktøyet som hører til.
Hver kontroll
Det er elleve sjekker. Ti av dem produserer én rad hver; adressesjekken produserer én rad per vert, så en full kjøring har tretten rader. Ni sjekker må bli godkjent, og et avvik er en feil. To, grafikknodene og sertifikatet, bør bli godkjent, og et avvik er en advarsel. Den siste kolonnen er kravteksten hver rad tar med seg inn i rapporten; CPU i den står for prosessor (central processing unit).
| Sjekk-ID | Del | Må godkjennes | Krav den skriver ut |
|---|---|---|---|
kubernetes-version |
cluster | ja | Kubernetes 1.33 eller nyere |
nodes-ready |
cluster | ja | Hver node er klar |
storage-class |
cluster | ja | En lagringsklasse for dataene |
resources |
cluster | ja | Nok CPU og minne for utgivelsen |
graphics-nodes |
cluster | nei | Grafikknoder |
ingress-class |
network | ja | En ingress-klasse for de tre adressene |
ingress-ports |
network | ja | Ingress-kontrolleren er åpen på port 80 og 443 |
address-console, address-api, address-auth |
network | ja | Konsoll-, api- eller auth-adressen løses i DNS |
certificate |
network | nei | Sertifikatet er gyldig i 30 dager til |
custodians |
time-and-keys | ja | Personene som sitter på denne installasjonens gjenopprettingsnøkler |
installation-name |
time-and-keys | ja | Denne installasjonens eget permanente navn |
kubernetes-version
Leser API-serverens versjon og sammenligner den med chartets nedre grense. Den finner for eksempel 1.33.6+k3s1. Under 1.33 feiler den med løsningen upgrade the cluster to 1.33 or later. Hvis versjonsstrengen ikke er en som nexusctl kan lese, feiler den i stedet for å gjette.
nodes-ready
Lister opp nodene og teller de der tilstanden Ready er sann, som 3 of 3. Enhver node som ikke er klar, navngis, og løsningen ber deg bringe den tilbake til Ready og lese tilstandene dens. En klynge uten noder i det hele tatt feiler med et hint om at konteksten kan peke på feil klynge.
storage-class
Hvis verdiene dine angir storage.className, slår sjekken opp den klassen og feiler med <name> does not exist når den mangler. Hvis de ikke gjør det, ser den etter en klasse som er merket som standard, og rapporterer den som local-path (default). Uten noen standard feiler den med none marked default, og kravkolonnen sier hvorfor det betyr noe: the database cannot claim a disk. Hvis to klasser er merket som standard, tildeler klyngen den nyeste klassen til et nytt krav, så det er den som rapporteres.
resources
Regner ut hva utgivelsen ber om ut fra chartet og verdiene dine, og legger deretter sammen de allokerbare prosessorkjernene (CPU) og minnet på hver node som er Ready, ikke avsperret (cordoned), og ikke har noen NoSchedule- eller NoExecute-taint. Chartets podder har ingen toleranser, så en node med taint kan ikke kjøre dem og teller ikke med. En klynge med for lite ressurser feiler med det nøyaktige underskuddet, slik som add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Behov rundes opp og tilgjengelig kapasitet rundes ned, slik at sjekken aldri smigrer deg.
graphics-nodes
Ser etter en Ready-node med en grafikkprosessor (GPU) den kan allokere, nvidia.com/gpu. Uten noen advarer den: the assistant will need a hosted model. Forhåndssjekken behandler dette som et råd og blokkerer aldri på grunn av det, fordi assistenten kan svare gjennom en vertsbasert modell for kunstig intelligens (KI) i stedet. Kapittel 2.14, KI-leverandører og -modeller, dekker begge veiene.
ingress-class
Hvis ingress.className er angitt, slår sjekken opp den klassen. Hvis ikke, ser den etter nøyaktig én klasse som er merket som standard. To klasser som er merket som standard, gir også feil, fordi API-serveren da avviser en Ingress uten klasse. Sjekken hoppes over, og raden utelates, når ingress.enabled er false.
ingress-ports
Ser i navnerommet som er navngitt av networkPolicy.ingressNamespace (som standard kube-system, der k3s kjører Traefik) etter én LoadBalancer- eller NodePort-Service som eksponerer både 80 og 443. Chartets nettverkspolicy lar bare det navnerommet nå de tre offentlige Service-objektene, så en ingress-kontroller et hvilket som helst annet sted ville ikke kunne betjene Nexus selv om den lyttet. Løsningen nevner begge utveiene: eksponer kontrolleren der, eller sett networkPolicy.ingressNamespace til stedet der den kjører. Hoppes over når ingress.enabled er false.
address
Slår opp hosts.console, hosts.api og hosts.auth fra arbeidsstasjonen din, fem sekunder hver, og skriver ut én rad per vert. En vert uten oppføring feiler med <host> → no record. En vert som ikke er angitt, feiler med hosts.<key> is not set. Når et navn har flere adresser, viser raden den første, IPv4 før IPv6, og hvor mange flere det er.
certificate
Kjører bare når tls.mode er existing og tls.existingSecret navngir et Secret-objekt; med cert-manager eller none er det ikke noe eget sertifikat å lese, og raden utelates. Den leser tls.crt fra Secret-objektet i installasjonsnavnerommet og ingenting annet. Et sertifikat som er gyldig i 30 dager eller mer, godkjennes som ends 3 Nov 2027. Et som utløper tidligere, advarer med ends in 9 days; et som allerede er utløpt, advarer med ended 4 days ago. Et manglende Secret-objekt, eller et uten sertifikat i seg, advarer med løsningen.
custodians
Leser keys.custody.recipients. Uten noen feiler den med koden KEYS_CUSTODIAN_MISSING. Hvis en mottaker er eksempel-forvalteren fra chartets egne verdifiler, feiler den med KEYS_CUSTODIAN_EXAMPLE, fordi ingen sitter på den nøkkelen og installasjonens gjenopprettingsnøkler ville blitt forseglet til ingen. Ved godkjenning skrives antallet ut, slik som 3 custodians.
installation-name
Leser keys.installationName. Hvis den ikke er angitt, feiler den med INSTALLATION_NAME_MISSING. Hvis den er satt til eksempelnavnet fra chartets verdifiler, feiler den med INSTALLATION_NAME_EXAMPLE. Ved godkjenning skrives navnet ut. Kravkolonnen sier hvorfor denne er viktigere enn de fleste: the first key-store bootstrap mints the installation identity under it, permanently.
De to siste sjekkene rapporterer nøyaktig de kodene som selve chartet avviser en installasjon med. Forhåndssjekken bare forteller deg det først, før Helm har opprettet noe.
Rapportfilene
Hver kjøring lagrer to filer i --report-dir, navngitt etter tidspunktet den kjørte: preflight-2026-11-12-0902.txt, linjene slik de ble skrevet ut uten fargekoder, og preflight-2026-11-12-0902.json, den samme kjøringen i et fast format som et program kan lese. Terminalutskriften og de lagrede linjene kommer fra den samme listen, så de avviker aldri.
JSON-rapporten følger skjemaet nexus.preflight/v1:
| Felt | Hva den inneholder |
|---|---|
schema |
Nøyaktig nexus.preflight/v1 |
tool |
Et objekt: name (nexusctl) og version |
release |
Utgivelsen som ble sjekket |
ran_at |
Når den kjørte, i koordinert universaltid (UTC) |
context |
Kube-kontekstens navn |
values |
Kun verdifilens basisnavn |
read_only |
Alltid true |
checks |
Én oppføring per rad: id, section, name, requirement, must_pass, outcome (pass, warn eller fail), found, needs, fix, og ved et avvik med en maskinårsak, code |
counts |
passed, warnings og failed |
can_install |
true når ingenting feilet |
report_file |
Navnet på .txt-filen |
transcript |
Et objekt: title (nexusctl preflight) og lines, hver linje med sin kind (prompt, ok, warn, bad, note, out eller blank), sin text og at, og noen ganger marks |
Rapporten er laget for å vises før noen logger inn, så den inneholder ikke noe brukernavn, ikke noe vertsnavn for arbeidsstasjonen, ingen filbane, ikke noe token og ingenting fra kubeconfig-filen din. values er et basisnavn og context er kontekstens navn. Hvis rapporten fra en kjøring ville brutt noen av disse reglene, nekter nexusctl å skrive ut, lagre eller overlevere den, og sier fra om det. En rapport er på høyst 256 KiB, med høyst 64 sjekker og 512 tegn i hvert enkelt tekstfelt.
Hvordan rapporten når konsollen
Forhåndssjekkens eneste skriveoperasjon er den ferdige rapporten, som overleveres til installasjonens nøkkeltjeneste, nexus-keys, slik at konsollens installasjonsprogram kan vise den på forhåndssjekksiden før noen har gjort krav på installasjonen. --record avgjør om den skal forsøke:
--record |
Hva som skjer |
|---|---|
auto |
Overleverer rapporten bare når navnerommet har en nexus-keys-Deployment |
always |
Insisterer; forhåndssjekken avslutter med 2 hvis det ikke finnes noe å overlevere den til |
never |
Overleverer den ikke |
Så en kjøring før den første installasjonen har ingenting å overlevere til, og beholder rapporten på arbeidsstasjonen din. En kjøring etter installasjonen og før kravet registrerer den.
Overleveringen bruker din egen klyngetilgang. nexusctl kjører /app/nexus-keys preflight-record i keys-kontaineren til en klar nexus-keys-podd og sender rapporten på standard inndata. Det tilsvarer:
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonNøkkeltjenesten sjekker rapporten mot de samme reglene som nexusctl bruker, og beholder bare den nyeste. Når den er overlevert, skriver nexusctl ut én linje til som forteller det, og den lagrede JSON-filen får en note som registrerer overleveringen.
Konsollens installasjonsprogram leser den fra nøkkeltjenestens offentlige rute GET /v1/installation/preflight. Den ruten svarer bare mens installasjonen er uavhentet: før noen rapport er registrert, svarer den 404 RECORD_NOT_FOUND, og så snart noen gjør krav på installasjonen, svarer den ROUTE_NOT_FOUND for godt, nøyaktig slik kravruten gjør. En rapport som overleveres etter kravet, avvises med INSTALLATION_CLAIMED.
I konsollen vises en kjøring med feil som «Forhåndssjekk kan ikke fortsette»: antall feil, advarsler og godkjente, og deretter hver sjekk gruppert under «Må godkjennes» og «Bør godkjennes», med de som ikke ble godkjent først og ordene som ble funnet ved siden av hver. En kjøring uten feil får ikke den siden; konsollen går rett videre til kravet (kapittel 2.12, Den første kjøringen).
Tilgangen kjøringen trenger
Forhåndssjekken kjører som deg, med din kubeconfig. Kontoen må kunne lese:
- noder, for sjekkene av versjon, klargjøring, ressurser og grafikk;
- lagringsklasser og ingress-klasser;
- Service-objekter i ingress-navnerommet;
- TLS-Secret-objektet i installasjonsnavnerommet, når sertifikatsjekken kjører.
Når en lesing nektes, sier raden could not read <what> (the cluster refused), og løsningen sier hvilken lesetilgang som må gis. Ordene inkluderer aldri serverens adresse eller dens egen feiltekst, fordi rapporten kan bli vist før innlogging. Overleveringen trenger også pods/exec på nexus-keys-poddene; uten dette lagrer auto filene og skriver ut en advarsel, og always avslutter med 2.
Når selve forhåndskontrollen ikke kan kjøre
Avslutningskode 2 betyr at det ikke ble laget noen rapport. Meldingen på standard feilutdata sier hvorfor:
| Melding | Hva du skal gjøre |
|---|---|
--context is required: the kube context to check |
Legg til --context |
--values is required: the values file the install will use |
Legg til --values |
could not read the values file harrow-values.yaml |
Sjekk banen og filens tillatelser |
preflight takes flags only |
Fjern det overflødige argumentet |
the report breaks its contract and was not printed, saved or handed over |
Et felt ville ha inneholdt noe privat; rapporter det til Adverant med kjøringens flagg |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
Installer først, eller bruk --record auto |
could not hand the report to this installation |
Sjekk tilgangen din til å kjøre exec inn i nexus-keys |
En klynge hvis API ikke kan nås, avslutter også med 2. Rett opp kubeconfig-filen eller nettverket, og kjør den på nytt.
Når forhåndssjekken avsluttes med 0 failed, går du videre til kapittel 2.6, Installere Community på Kubernetes, for å installere Community, eller kapittel 2.7, Installere Enterprise og legge inn en lisens, for Enterprise.

