Version 1.0.0-alpha.1seneste
Kapitel 2.5
Forhåndskontrol med nexusctl
Hver kontrol `nexusctl preflight` foretager, hvad hver enkelt læser, og hvordan den fejler, rapporten den udskriver og gemmer, hvordan den rapport når frem til konsollens side for forhåndskontrol, samt hvert enkelt flag.
Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

Vores første forhåndskontrol hos Harrow Port Authority dumpede på fire tjek, og to af dem ville have kostet os langt mere end en eftermiddag. Vi havde påbegyndt værdifilen ved at kopiere diagrammets eksempel, og forhåndskontrollen afviste både eksempelinstallationsnavnet og eksempelvogteren. Ingen ligger inde med den vogters private nøgle. En installation, der er forseglet til den, kan aldrig åbnes igen efter en genstart af en node. Forhåndskontrollen fangede det på få sekunder, før der fandtes noget at miste.
nexusctl preflight læser din klynge og din værdifil, udskriver hvad den fandt, gemmer en rapport og ændrer intet i klyngen. Kør den før hver installation og hver opgradering. Dette kapitel gennemgår hvert tjek, den foretager, rapportformatet, hvor rapporten gemmes, samt tilvalgene (flags).
Drift
Forhåndskontrollen kræver to ting: kube-konteksten for den klynge, du vil installere på, og den værdifil, som installationen skal bruge. Skriv værdifilen først; kapitel 2.6, Installation af Community på Kubernetes, gennemgår hver nøgle. Derefter:
nexusctl preflight --context harrow-prod --values harrow-values.yamlDen læser klyngen via client-go udelukkende med get- og list-kald. Hvis din tls.mode er existing, skal du oprette navnerummet nexus og din Transport Layer Security (TLS) Secret, før du kører den (kapitel 2.6, Installation af Community på Kubernetes, trin 3), ellers rapporterer certifikattjekket, at din Secret mangler.
| Tilvalg | Hvad den gør | Standard |
|---|---|---|
--context <name> |
Den kube-kontekst, der skal tjekkes. Påkrævet | ingen |
--values <file> |
Den værdifil, som installationen skal bruge. Påkrævet | ingen |
--namespace <name> |
Hvor Nexus installeres | nexus |
--release <version> |
Den udgivelse, der tjekkes | det medfølgende diagrams egen version |
--report-dir <dir> |
Hvor de to rapportfiler gemmes | den aktuelle mappe |
--record <mode> |
auto, always eller never: hvorvidt rapporten skal overdrages til denne installations nøgletjeneste, så dens installationsside viser den |
auto |
--kubeconfig <file> |
Den kubeconfig, der skal læses | KUBECONFIG, derefter ~/.kube/config |
--ca-bundle <file> |
Dine egne certifikatautoritetscertifikater (CA) til en kæde, som tjekkene skal stole på | ingen |
--single-node |
Tjek én maskine til en enkeltmaskineinstallation (kapitel 2.8, Enkeltmaskineinstallationer) | fra |
Udgivelsens minimumsgrænse for Kubernetes er ikke indkodet i nexusctl. Den aflæser den nedre grænse for diagrammets egen kubeVersion fra det diagram, den medbringer, så tjekket og helm install aldrig kan være uenige.
Hvad en kørsel udskriver
Her er Harrows første kørsel, som den blev udskrevet:
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 noget fejler, kommer fejlene først, derefter advarslerne og til sidst de beståede tjek. Hver række viser resultatet, tjekkets navn, hvad der blev fundet, og hvad det kræver; hver række, der ikke bestod, har en fix-linje under sig. De sidste to linjer er sammenfatningen og rapportfilen.
Vi rettede værdierne, tilføjede de to Domain Name System (DNS)-poster, oprettede den pågældende Secret og kørte den igen:
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 kørsel uden fejl viser tjekkene under deres tre overskrifter: Klynge, Netværk samt Tid og nøgler. Advarsler blokerer aldrig. Vi beholdt grafikadvarslen med vilje: På denne tilsluttede pilotklynge brugte Harrows assistent en hostet model med havnens egen nøgle.
Afslutningskoder
| Kode | Betydning |
|---|---|
0 |
Installationen kan fortsætte. Advarsler blokerer ikke |
1 |
Installationen er blokeret: mindst ét tjek fejlede |
2 |
Forhåndskontrollen kunne ikke køre: kubeconfig, konteksten, værdifilen eller klyngens applikationsprogrammeringsgrænseflade (API) kunne ikke læses, eller et tilvalg var forkert |
Scripts bør aflæse afslutningskoden (exit code), ikke ordene. Vores kører forhåndskontrollen som det første trin ved hver opgradering og stopper ved alt andet end 0.
Kør nexusctl fra den udgivelse, du skifter til, ikke den, du installerede med. Kravene stammer fra det diagram, den medbringer, så en nyere udgivelse kan hæve minimumsgrænsen for Kubernetes eller kræve mere hukommelse, og kun dens egen nexusctl kender kravene. --release ændrer den version, som rapporten angiver; det ændrer ikke, hvilket diagrams regler der anvendes. Hos Harrow opbevarer vi hver udgivelses nexusctl sammen med dens diagram i ændringsloggen, så en tilbagerulning tjekkes af det værktøj, der passer til den.
Hver kontrol
Der er elleve tjek. Ti af dem giver én række hver; adressetjekket giver én række pr. vært (host), så en fuld kørsel har tretten rækker. Ni tjek skal bestås, og en afvigelse er en fejl. To – grafiknoderne og certifikatet – bør bestås, og en afvigelse er en advarsel. Den sidste kolonne er den kravtekst, hver række tager med over i rapporten; CPU deri står for central processing unit.
| Tjek-id | Sektion | Skal bestås | Krav, det udskriver |
|---|---|---|---|
kubernetes-version |
cluster | ja | Kubernetes 1.33 eller nyere |
nodes-ready |
cluster | ja | Hver node er klar |
storage-class |
cluster | ja | En lagerklasse (storage class) til dataene |
resources |
cluster | ja | Tilstrækkelig CPU og hukommelse til udgivelsen |
graphics-nodes |
cluster | nej | Grafiknoder |
ingress-class |
network | ja | En ingress-klasse til de tre adresser |
ingress-ports |
network | ja | Ingress-controlleren er åben på port 80 og 443 |
address-console, address-api, address-auth |
network | ja | Console-, api- eller auth-adressen kan slås op i DNS |
certificate |
network | nej | Certifikatet er gyldigt i yderligere 30 dage |
custodians |
time-and-keys | ja | De personer, der ligger inde med denne installations gendannelsesnøgler |
installation-name |
time-and-keys | ja | Denne installations eget permanente navn |
kubernetes-version
Læser API-serverens version og sammenligner den med diagrammets minimumsgrænse. Det finder for eksempel 1.33.6+k3s1. Under 1.33 fejler det med løsningen upgrade the cluster to 1.33 or later. Hvis versionsstrengen ikke er en, som nexusctl kan læse, fejler det frem for at gætte.
nodes-ready
Oplister noderne og tæller dem, hvis Ready-tilstand er sand, som 3 of 3. Enhver node, der ikke er klar, navngives, og løsningen beder dig om at bringe den tilbage i tilstanden Ready og aflæse dens tilstande. En klynge helt uden noder fejler med et tip om, at konteksten muligvis peger på den forkerte klynge.
storage-class
Hvis dine værdier angiver storage.className, slår tjekket den pågældende klasse op og fejler med <name> does not exist, når den mangler. Hvis de ikke gør det, leder det efter en klasse markeret som standard og rapporterer den som local-path (default). Uden en standard fejler det med none marked default, og kravkolonnen forklarer, hvorfor det er vigtigt: the database cannot claim a disk. Hvis to klasser er markeret som standard, tildeler klyngen den nyeste til en ny anmodning (claim), så det er den, der rapporteres.
resources
Beregner, hvad udgivelsen kræver ud fra diagrammet og dine værdier, og lægger derefter de allokerbare central processing unit (CPU)-kerner og hukommelsen sammen for hver node, der er Ready, ikke er afspærret (cordoned) og ikke har en NoSchedule- eller NoExecute-taint. Diagrammets pods har ingen tolerations, så en node med taint kan ikke køre dem og tæller ikke med. En klynge med utilstrækkelige ressourcer fejler med det nøjagtige underskud, så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 op, og kapacitet rundes ned, så tjekket giver aldrig et for optimistisk billede.
graphics-nodes
Leder efter en Ready-node med en graphics processing unit (GPU), som den kan allokere, nvidia.com/gpu. Hvis der ingen er, advarer den: the assistant will need a hosted model. Forhåndskontrollen behandler det som en anbefaling og blokerer aldrig på det, fordi assistenten i stedet kan svare via en hostet model til kunstig intelligens (AI). Kapitel 2.14, AI-udbydere og -modeller, dækker begge veje.
ingress-class
Hvis ingress.className er angivet, slår tjekket den klasse op. Hvis ikke, leder det efter nøjagtigt én klasse markeret som standard. To klasser markeret som standard udløser også en fejl, fordi API-serveren i så fald afviser en Ingress uden klasse. Tjekket springes over, og dets række udelades, når ingress.enabled er false.
ingress-ports
Leder i det navnerum, der er angivet af networkPolicy.ingressNamespace (som standard kube-system, hvor k3s kører Traefik), efter én LoadBalancer- eller NodePort-Service, der eksponerer både 80 og 443. Diagrammets netværkspolitik tillader kun det pågældende navnerum at nå de tre offentlige Services, så en ingress-controller et hvilket som helst andet sted ville ikke kunne betjene Nexus, selv hvis den lyttede. Løsningen nævner begge udveje: eksponer controlleren dér, eller sæt networkPolicy.ingressNamespace til det sted, hvor den kører. Springes over, når ingress.enabled er false.
address
Slår hosts.console, hosts.api og hosts.auth op fra din arbejdsstation, fem sekunder hver, og udskriver én række pr. vært. En vært uden post fejler med <host> → no record. En vært, der ikke er angivet, fejler med hosts.<key> is not set. Når et navn har flere adresser, viser rækken den første, IPv4 før IPv6, samt hvor mange flere der er.
certificate
Kører kun, når tls.mode er existing, og tls.existingSecret navngiver en Secret; med cert-manager eller none er der ikke noget certifikat fra din side at læse, og rækken udelades. Det læser tls.crt fra den pågældende Secret i installationsnavnerummet og intet andet. Et certifikat, der er gyldigt i 30 dage eller mere, består som ends 3 Nov 2027. Et, der udløber tidligere, advarer med ends in 9 days; et, der allerede er udløbet, advarer med ended 4 days ago. En manglende Secret, eller en uden et certifikat i, advarer med løsningen.
custodians
Læser keys.custody.recipients. Hvis der ingen er, fejler det med koden KEYS_CUSTODIAN_MISSING. Hvis en modtager er eksempelvogteren fra diagrammets egne værdifiler, fejler det med KEYS_CUSTODIAN_EXAMPLE, fordi ingen ligger inde med den nøgle, og installationens gendannelsesnøgler ville blive forseglet til ingen. Et bestået tjek udskriver antallet, såsom 3 custodians.
installation-name
Læser keys.installationName. Hvis det ikke er angivet, fejler det med INSTALLATION_NAME_MISSING. Hvis det er sat til eksempelnavnet fra diagrammets værdifiler, fejler det med INSTALLATION_NAME_EXAMPLE. Et bestået tjek udskriver navnet. Kravkolonnen forklarer, hvorfor netop dette er vigtigere end de fleste: the first key-store bootstrap mints the installation identity under it, permanently.
De sidste to tjek rapporterer nøjagtigt de koder, som selve diagrammet afviser en installation med. Forhåndskontrollen fortæller dig det blot først, før Helm har oprettet noget.
Rapportfilerne
Hver kørsel gemmer to filer i --report-dir, navngivet efter tidspunktet for kørslen: preflight-2026-11-12-0902.txt, linjerne som udskrevet uden farvekoder, og preflight-2026-11-12-0902.json, den samme kørsel i et fast format, som et program kan læse. Terminaludskriften og de gemte linjer stammer fra den samme liste, så de afviger aldrig fra hinanden.
JSON-rapporten følger skemaet nexus.preflight/v1:
| Felt | Hvad den indeholder |
|---|---|
schema |
Nøjagtigt nexus.preflight/v1 |
tool |
Et objekt: name (nexusctl) og version |
release |
Den tjekkede udgivelse |
ran_at |
Hvornår den kørte, i Coordinated Universal Time (UTC) |
context |
Kube-kontekstens navn |
values |
Kun værdifilens basisnavn |
read_only |
Altid true |
checks |
Én post pr. række: id, section, name, requirement, must_pass, outcome (pass, warn eller fail), found, needs, fix og, ved en afvigelse med en maskinårsag, code |
counts |
passed, warnings og failed |
can_install |
true, når intet fejlede |
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 undertiden marks |
Rapporten er skabt til at blive vist, før nogen logger ind, så den indeholder intet brugernavn, intet værtsnavn fra arbejdsstationen, ingen filsti, intet token og intet fra din kubeconfig. values er et basisnavn, og context er kontekstens navn. Hvis en kørsels rapport ville bryde nogen af disse regler, nægter nexusctl at udskrive, gemme eller overdrage den og giver besked herom. En rapport fylder højst 256 KiB, med højst 64 tjek og 512 tegn i et enkelt tekstfelt.
Hvordan rapporten når frem til konsollen
Forhåndskontrollens eneste skrivehandling er den færdige rapport, der overdrages til installationens nøgletjeneste, nexus-keys, så konsollens installationsprogram kan vise den på sin side for forhåndskontrol, før nogen har gjort krav på installationen. --record afgør, om det skal forsøges:
--record |
Hvad der sker |
|---|---|
auto |
Overdrager kun rapporten, når navnerummet har et nexus-keys-Deployment |
always |
Insisterer; forhåndskontrollen afslutter med 2, hvis der ikke er noget at overdrage den til |
never |
Overdrager den ikke |
Så en kørsel før den første installation har ikke noget at overdrage til og beholder rapporten på din arbejdsstation. En kørsel efter installationen og før overtagelsen (claim) registrerer den.
Overdragelsen bruger din egen klyngeadgang. nexusctl kører /app/nexus-keys preflight-record i keys-containeren på en klar nexus-keys-pod og sender rapporten via standard input. Det svarer til:
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonNøgletjenesten tjekker rapporten mod de samme regler, som nexusctl anvender, og gemmer kun den seneste. Når den er overdraget, udskriver nexusctl endnu en linje, der fortæller det, og den gemte JSON får en note, der registrerer overdragelsen.
Konsollens installationsprogram læser den fra nøgletjenestens offentlige rute GET /v1/installation/preflight. Den rute svarer kun, mens installationen er uovertaget: Før en rapport er registreret, svarer den 404 RECORD_NOT_FOUND, og når nogen gør krav på installationen, svarer den ROUTE_NOT_FOUND permanent, præcis som overtagelsesruten gør. En rapport, der overdrages efter overtagelsen, afvises med INSTALLATION_CLAIMED.
I konsollen vises en kørsel med fejl som "Forhåndskontrol kan ikke fortsætte": antallet af fejlede, advarsler og beståede, derefter hvert tjek grupperet under "Skal bestås" og "Bør bestås", med dem, der ikke bestod, først og de fundne værdier ved siden af hver. En kørsel uden fejl får ikke den side; konsollen går direkte videre til overtagelsen (kapitel 2.12, Den første kørsel).
Adgang, som kørslen kræver
Forhåndskontrollen kører som dig med din kubeconfig. Kontoen skal have læseadgang til:
- noder, til tjekkene af version, klarhed, ressourcer og grafik;
- lagerklasser (storage classes) og ingress-klasser;
- Services i ingress-navnerummet;
- den pågældende TLS Secret i installationsnavnerummet, når certifikattjekket kører.
Når en læsning afvises, viser rækken could not read <what> (the cluster refused), og løsningen angiver, hvilken læseadgang der skal tildeles. Teksten indeholder aldrig serverens adresse eller dens egen fejltekst, fordi rapporten kan blive vist før login. Overdragelsen kræver også pods/exec på nexus-keys-pods; uden den gemmer auto filerne og udskriver en advarsel, og always afslutter med 2.
Når selve forhåndskontrollen ikke kan køre
Afslutningskode 2 betyder, at der ikke blev oprettet nogen rapport. Beskeden på standard error forklarer hvorfor:
| Besked | Hvad du skal gøre |
|---|---|
--context is required: the kube context to check |
Tilføj --context |
--values is required: the values file the install will use |
Tilføj --values |
could not read the values file harrow-values.yaml |
Tjek stien og filens tilladelser |
preflight takes flags only |
Fjern det overskydende argument |
the report breaks its contract and was not printed, saved or handed over |
Et felt ville have indeholdt noget privat; rapporter det til Adverant med kørslens tilvalg |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
Installer først, eller brug --record auto |
could not hand the report to this installation |
Tjek din adgang til at køre exec ind i nexus-keys |
En klynge, hvis API ikke kan nås, afslutter også med 2. Ret din kubeconfig eller netværket, og kør den igen.
Når forhåndskontrollen slutter med 0 failed, skal du gå videre til kapitel 2.6, Installation af Community på Kubernetes, for at installere Community, eller kapitel 2.7, Installation af Enterprise og anvendelse af en licens, for Enterprise.

