Logg innBestill en gjennomgang

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

16 minutter å lese

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

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

Før du installerer
Før du installerer
Forhåndssjekk i operatørens terminal, med antallene ved siden av. Legg merke til at hver advarsel har løsningen skrevet ut under seg, og at kjøringen tydelig sier at den ikke endret noe i klyngen.

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

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

Forhåndssjekk kan ikke fortsette
Forhåndssjekk kan ikke fortsette
Konsollens side for en forhåndssjekk-kjøring som ikke kan fortsette. Sjekkene som feiler kommer først, hver av dem beskrevet med ord og hva som ble funnet, og installasjonen forblir blokkert til de blir godkjent.
Tre kolonner. Til venstre, «Operatørens arbeidsstasjon»: en boks «nexusctl preflight --context --values» med to utdata under seg, «preflight-<time>.txt» og «preflight-<time>.json». I midten, «Installasjonen, uavhentet»: en boks «nexus-keys» med etiketten «preflight-record, kun nyeste rapport». En pil fra den venstre boksen til nexus-keys har etiketten «pod exec med din egen klyngetilgang (--record auto eller always)». Til høyre, «Nettleser, før innlogging»: en boks «Konsollens installasjonsprogram, Forhåndssjekk kan ikke fortsette». En pil fra nexus-keys til den har etiketten «GET /v1/installation/preflight». Under den midterste boksen står en liten merknad: «etter kravet: ROUTE_NOT_FOUND».
Hvor én forhåndssjekk-rapport tar veien, fra operatørens arbeidsstasjon til nettleseren.

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.