Log indBook en briefing

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

16 minutters læsetid

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

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

Før du installerer
Før du installerer
Forhåndskontrol i operatørens terminal med optællingerne ved siden af. Bemærk, at hver advarsel har sin løsning udskrevet under sig, og at kørslen tydeligt angiver, at den intet har ændret i klyngen.

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

Nø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).

Forhåndskontrol kan ikke fortsætte
Forhåndskontrol kan ikke fortsætte
Konsollens side for en forhåndskontrolkørsel, der ikke kan fortsætte. De fejlede tjek kommer først, hvert beskrevet med ord og hvad der blev fundet, og installationen forbliver blokeret, indtil de består.
Tre kolonner. Til venstre, "Operatørens arbejdsstation": en boks "nexusctl preflight --context --values" med to output under sig, "preflight-<time>.txt" og "preflight-<time>.json". I midten, "Installationen, uovertaget": en boks "nexus-keys" med mærkaten "preflight-record, kun seneste rapport". En pil fra den venstre boks til nexus-keys har mærkaten "pod exec med din egen klyngeadgang (--record auto eller always)". Til højre, "Browser, før login": en boks "Konsolinstallationsprogram, Forhåndskontrol kan ikke fortsætte". En pil fra nexus-keys til den har mærkaten "GET /v1/installation/preflight". Under den midterste boks står en lille note: "efter overtagelsen: ROUTE_NOT_FOUND".
Hvor en rapport fra forhåndskontrollen bevæger sig hen, fra operatørens arbejdsstation til browseren.

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.