InloggenBriefing plannen

Hoofdstuk 2.5

Preflight met nexusctl

Elke controle die `nexusctl preflight` uitvoert, wat elke controle leest en hoe deze faalt, het rapport dat wordt afgedrukt en opgeslagen, hoe dat rapport de preflight-pagina van de console bereikt, en elke vlag.

Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

16 minuten leestijd

Onze eerste preflight bij Harrow Port Authority faalde bij vier controles, en twee daarvan zouden ons veel meer dan een middag hebben gekost. We waren het values-bestand begonnen door het voorbeeld van de chart te kopiëren, en preflight weigerde zowel de voorbeeld-installatienaam als de voorbeeld-beheerder. Niemand bezit de privésleutel van die beheerder. Een installatie die daarmee is verzegeld, kan na een herstart van een node nooit meer worden ontzegeld. Preflight onderschepte dat in een paar seconden, nog voordat er iets bestond om te verliezen.

nexusctl preflight leest uw cluster en uw values-bestand, drukt af wat het heeft gevonden, slaat een rapport op en wijzigt niets op het cluster. Voer dit uit vóór elke installatie en elke upgrade. Dit hoofdstuk behandelt elke controle die het uitvoert, het rapportformaat, waar het rapport naartoe gaat en de vlaggen.

Het beheer

Preflight heeft twee dingen nodig: de kube-context van het cluster waarop u gaat installeren, en het values-bestand dat de installatie gaat gebruiken. Schrijf eerst het values-bestand; hoofdstuk 2.6, Community installeren op Kubernetes, doorloopt elke sleutel. Vervolgens:

nexusctl preflight --context harrow-prod --values harrow-values.yaml

Het leest het cluster via client-go uitsluitend met get- en list-aanroepen. Als uw tls.mode existing is, maak dan de nexus-namespace en het Transport Layer Security (TLS) Secret aan voordat u het uitvoert (hoofdstuk 2.6, Community installeren op Kubernetes, stap 3), anders meldt de certificaatcontrole dat het Secret ontbreekt.

Vlag Wat deze doet Standaard
--context <name> De te controleren kube-context. Vereist geen
--values <file> Het values-bestand dat de installatie gaat gebruiken. Vereist geen
--namespace <name> Waar Nexus wordt geïnstalleerd nexus
--release <version> De release die wordt gecontroleerd de eigen versie van de meegeleverde chart
--report-dir <dir> Waar de twee rapportbestanden worden opgeslagen de huidige map
--record <mode> auto, always of never: of het rapport moet worden overgedragen aan de sleutelservice van deze installatie, zodat haar installatiepagina het toont auto
--kubeconfig <file> De te lezen kubeconfig KUBECONFIG, daarna ~/.kube/config
--ca-bundle <file> Uw eigen certificaten van een certificaatautoriteit (CA), voor een keten die de controles moeten vertrouwen geen
--single-node Controleer één machine voor een installatie op één machine (hoofdstuk 2.8, Installaties op één machine) uit

De ondergrens van de release voor Kubernetes is niet ingetypt in nexusctl. Het leest de ondergrens van de eigen kubeVersion van de chart uit de chart die het bij zich draagt, zodat de controle en helm install het nooit oneens kunnen zijn.

Wat een uitvoering afdrukt

Hier is de eerste uitvoering van Harrow, zoals deze werd afgedrukt:

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

Wanneer er iets mislukt, komen eerst de fouten, daarna de waarschuwingen en vervolgens de geslaagde controles. Elke rij toont het resultaat, de naam van de controle, wat er is gevonden en wat er nodig is; onder elke rij die niet is geslaagd, staat een fix-regel. De laatste twee regels zijn de samenvatting en het rapportbestand.

We hebben de waarden hersteld, de twee Domain Name System (DNS)-records toegevoegd, het Secret aangemaakt en het opnieuw uitgevoerd:

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

Een uitvoering zonder fouten toont de controles onder hun drie kopjes: Cluster, Netwerk, en Tijd en sleutels. Waarschuwingen blokkeren nooit. We hebben de grafische waarschuwing met opzet behouden: op dit verbonden pilotcluster gebruikte de assistent van Harrow een gehost model met de eigen sleutel van de haven.

Voordat u installeert
Voordat u installeert
Preflight in de terminal van de operator, met de aantallen ernaast. Merk op dat onder elke waarschuwing de bijbehorende oplossing is afgedrukt en dat de uitvoering duidelijk vermeldt dat er niets op het cluster is gewijzigd.

Exitcodes

Code Betekenis
0 De installatie kan doorgaan. Waarschuwingen blokkeren niet
1 De installatie is geblokkeerd: ten minste één controle is mislukt
2 Preflight kon niet worden uitgevoerd: de kubeconfig, de context, het values-bestand of de application programming interface (API) van het cluster kon niet worden gelezen, of een vlag was onjuist

Scripts moeten de exitcode lezen, niet de woorden. Die van ons voert preflight uit als de eerste stap van elke upgrade en stopt bij alles behalve 0.

Voer de nexusctl uit van de release waarnaar u overstapt, niet die waarmee u hebt geïnstalleerd. De vereisten komen uit de chart die het bij zich draagt, dus een nieuwere release kan de ondergrens voor Kubernetes verhogen of om meer geheugen vragen, en alleen zijn eigen nexusctl weet dat. --release wijzigt de versie die het rapport noemt; het verandert niet van welke chart de regels worden toegepast. Bij Harrow bewaren we de nexusctl van elke release naast de bijbehorende chart in het wijzigingsregister, zodat een rollback wordt gecontroleerd door de tool die daarbij hoort.

Elke controle

Er zijn elf controles. Tien daarvan produceren elk één rij; de adrescontrole produceert één rij per host, dus een volledige uitvoering telt dertien rijen. Negen controles moeten slagen, en een misser is een fout. Twee, de grafische nodes en het certificaat, zouden moeten slagen, en een misser is een waarschuwing. De laatste kolom is de vereistentekst die elke rij meeneemt naar het rapport; CPU staat daarin voor de central processing unit.

Controle-id Sectie Moet slagen Vereiste die wordt afgedrukt
kubernetes-version cluster ja Kubernetes 1.33 of nieuwer
nodes-ready cluster ja Elke node gereed
storage-class cluster ja Een opslagklasse voor de gegevens
resources cluster ja Voldoende CPU en geheugen voor de release
graphics-nodes cluster nee Grafische nodes
ingress-class network ja Een ingress-klasse voor de drie adressen
ingress-ports network ja De ingress-controller open op poort 80 en 443
address-console, address-api, address-auth network ja Het console-, api- of auth-adres wordt omgezet in DNS
certificate network nee Certificaat nog 30 dagen geldig
custodians time-and-keys ja De mensen die de herstelsleutels van deze installatie beheren
installation-name time-and-keys ja De eigen permanente naam van deze installatie

kubernetes-version

Leest de versie van de API-server en vergelijkt deze met de ondergrens van de chart. Het vindt bijvoorbeeld 1.33.6+k3s1. Onder 1.33 mislukt het met de oplossing upgrade the cluster to 1.33 or later. Als de versietekenreeks er niet een is die nexusctl kan lezen, mislukt het in plaats van te raden.

nodes-ready

Maakt een lijst van de nodes en telt de exemplaren waarvan de Ready-conditie waar is, als 3 of 3. Elke node die niet gereed is, wordt bij naam genoemd, en de oplossing instrueert u om deze terug naar Ready te brengen en de condities ervan te lezen. Een cluster zonder enige node mislukt met een aanwijzing dat de context mogelijk naar het verkeerde cluster verwijst.

storage-class

Als uw waarden storage.className instellen, zoekt de controle die klasse op en mislukt met <name> does not exist wanneer deze ontbreekt. Als ze dat niet doen, zoekt het naar een klasse die als standaard is gemarkeerd en rapporteert deze als local-path (default). Zonder standaardklasse mislukt het met none marked default, en de kolom met benodigdheden vermeldt waarom dat belangrijk is: the database cannot claim a disk. Als twee klassen als standaard zijn gemarkeerd, geeft het cluster een nieuwe claim de nieuwste, dus dat is degene die wordt gerapporteerd.

resources

Berekent wat de release vraagt op basis van de chart en uw waarden, en telt vervolgens de toewijsbare central processing unit (CPU)-kernen en het geheugen op van elke node die Ready is, niet is afgegrendeld (cordoned), en geen NoSchedule- of NoExecute-taint heeft. De pods van de chart hebben geen tolerations, dus een node met een taint kan ze niet uitvoeren en telt niet mee. Een cluster dat tekortkomt, mislukt met het exacte tekort, zoals add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Benodigdheden worden naar boven afgerond en het aanbod naar beneden, zodat de controle het nooit rooskleuriger voorstelt dan het is.

graphics-nodes

Zoekt naar een Ready-node met een graphics processing unit (GPU) die kan worden toegewezen, nvidia.com/gpu. Als er geen is, waarschuwt het: the assistant will need a hosted model. Preflight behandelt dit als advies en blokkeert er nooit op, omdat de assistent in plaats daarvan kan antwoorden via een gehost artificial intelligence (AI)-model. Hoofdstuk 2.14, AI-providers en -modellen, behandelt beide routes.

ingress-class

Als ingress.className is ingesteld, zoekt de controle die klasse op. Zo niet, dan zoekt het naar precies één klasse die als standaard is gemarkeerd. Twee klassen die als standaard zijn gemarkeerd mislukken ook, omdat de API-server dan een Ingress zonder klasse weigert. De controle wordt overgeslagen en de bijbehorende rij wordt weggelaten wanneer ingress.enabled gelijk is aan false.

ingress-ports

Zoekt in de namespace die is genoemd door networkPolicy.ingressNamespace (standaard kube-system, waar k3s Traefik uitvoert) naar één LoadBalancer- of NodePort-Service die zowel 80 als 443 openstelt. Het netwerkbeleid van de chart laat alleen die namespace de drie openbare Services bereiken, dus een ingress-controller op een andere plek zou Nexus niet kunnen bedienen, zelfs niet als deze zou luisteren. De oplossing noemt beide uitwegen: stel de controller daar open, of stel networkPolicy.ingressNamespace in op de plek waar deze draait. Wordt overgeslagen wanneer ingress.enabled gelijk is aan false.

address

Zoekt hosts.console, hosts.api en hosts.auth op vanaf uw werkstation, elk vijf seconden, en drukt één rij per host af. Een host zonder record mislukt met <host> → no record. Een niet-ingestelde host mislukt met hosts.<key> is not set. Wanneer een naam meerdere adressen heeft, toont de rij het eerste, IPv4 vóór IPv6, en hoeveel er nog meer zijn.

certificate

Wordt alleen uitgevoerd wanneer tls.mode gelijk is aan existing en tls.existingSecret een Secret noemt; met cert-manager of none is er geen eigen certificaat om te lezen en wordt de rij weggelaten. Het leest tls.crt uit het Secret in de installatie-namespace en niets anders. Een certificaat dat nog 30 dagen of langer geldig is, slaagt als ends 3 Nov 2027. Een certificaat dat eerder verloopt, waarschuwt met ends in 9 days; een dat al is verlopen, waarschuwt met ended 4 days ago. Een ontbrekend Secret, of een zonder certificaat erin, waarschuwt met de oplossing.

custodians

Leest keys.custody.recipients. Zonder waarden mislukt het met de code KEYS_CUSTODIAN_MISSING. Als een ontvanger de voorbeeld-beheerder uit de eigen values-bestanden van de chart is, mislukt het met KEYS_CUSTODIAN_EXAMPLE, omdat niemand die sleutel bezit en de herstelsleutels van de installatie aan niemand zouden worden verzegeld. Bij slagen wordt het aantal afgedrukt, zoals 3 custodians.

installation-name

Leest keys.installationName. Indien niet ingesteld, mislukt het met INSTALLATION_NAME_MISSING. Indien ingesteld op de voorbeeldnaam uit de values-bestanden van de chart, mislukt het met INSTALLATION_NAME_EXAMPLE. Bij slagen wordt de naam afgedrukt. De kolom met benodigdheden vermeldt waarom deze belangrijker is dan de meeste andere: the first key-store bootstrap mints the installation identity under it, permanently.

De laatste twee controles rapporteren precies de codes waarmee de chart zelf een installatie weigert. Preflight vertelt het u alleen als eerste, voordat Helm iets heeft aangemaakt.

De rapportbestanden

Elke uitvoering slaat twee bestanden op in --report-dir, genoemd naar het tijdstip waarop deze plaatsvond: preflight-2026-11-12-0902.txt, de regels zoals afgedrukt zonder kleurcodes, en preflight-2026-11-12-0902.json, dezelfde uitvoering in een vast formaat dat een programma kan lezen. De terminaluitvoer en de opgeslagen regels komen uit dezelfde lijst, zodat ze nooit van elkaar verschillen.

Het JSON-rapport volgt het schema nexus.preflight/v1:

Veld Wat het bevat
schema Precies nexus.preflight/v1
tool Een object: name (nexusctl) en version
release De gecontroleerde release
ran_at Wanneer het werd uitgevoerd, in Coordinated Universal Time (UTC)
context De naam van de kube-context
values Alleen de basisnaam van het values-bestand
read_only Altijd true
checks Eén vermelding per rij: id, section, name, requirement, must_pass, outcome (pass, warn of fail), found, needs, fix, en bij een misser met een machine-oorzaak, code
counts passed, warnings en failed
can_install true wanneer er niets is mislukt
report_file De naam van het .txt-bestand
transcript Een object: title (nexusctl preflight) en lines, elke regel met zijn kind (prompt, ok, warn, bad, note, out of blank), zijn text en at, en soms marks

Het rapport is gebouwd om te worden getoond voordat iemand zich aanmeldt, dus het bevat geen gebruikersnaam, geen hostnaam van het werkstation, geen bestandspad, geen token en niets uit uw kubeconfig. values is een basisnaam en context is de naam van de context. Als het rapport van een uitvoering een van die regels zou overtreden, weigert nexusctl het af te drukken, op te slaan of over te dragen, en meldt dat ook. Een rapport is maximaal 256 KiB groot, met maximaal 64 controles en 512 tekens in elk afzonderlijk tekstveld.

Hoe het rapport de console bereikt

De enige schrijfactie van preflight is het voltooide rapport, dat wordt overgedragen aan de sleutelservice van de installatie, nexus-keys, zodat het installatieprogramma van de console het op zijn preflight-pagina kan tonen voordat iemand de installatie heeft geclaimd. --record bepaalt of dit wordt geprobeerd:

--record Wat er gebeurt
auto Draagt het rapport alleen over wanneer de namespace een nexus-keys-Deployment heeft
always Dringt aan; preflight sluit af met 2 als er niets is om het aan over te dragen
never Draagt het niet over

Een uitvoering vóór de eerste installatie heeft dus niets om aan over te dragen en bewaart het rapport op uw werkstation. Een uitvoering na de installatie en vóór de claim legt het vast.

De overdracht maakt gebruik van uw eigen clustertoegang. nexusctl voert /app/nexus-keys preflight-record uit in de keys-container van een gereedstaande nexus-keys-pod en geeft het rapport door via standaardinvoer. Het is hetzelfde als:

kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.json

De sleutelservice controleert het rapport aan de hand van dezelfde regels die nexusctl toepast en bewaart alleen het nieuwste exemplaar. Wanneer het is overgedragen, drukt nexusctl nog één regel af om dat te melden en krijgt de opgeslagen JSON een note die de overdracht vastlegt.

Het installatieprogramma van de console leest het vanaf de openbare route GET /v1/installation/preflight van de sleutelservice. Die route antwoordt alleen zolang de installatie niet is geclaimd: voordat er een rapport is vastgelegd, antwoordt deze met 404 RECORD_NOT_FOUND, en zodra iemand de installatie claimt, antwoordt deze voorgoed met ROUTE_NOT_FOUND, precies zoals de claimroute dat doet. Een rapport dat na de claim wordt overgedragen, wordt geweigerd met INSTALLATION_CLAIMED.

Op de console verschijnt een uitvoering met fouten als "Preflight kan niet doorgaan": de aantallen mislukte, gewaarschuwde en geslaagde controles, gevolgd door elke controle gegroepeerd onder "Moet slagen" en "Zou moeten slagen", met de controles die niet zijn geslaagd als eerste en de gevonden woorden naast elk ervan. Een uitvoering zonder fouten krijgt die pagina niet; de console gaat direct door naar de claim (hoofdstuk 2.12, De eerste uitvoering).

Preflight kan niet doorgaan
Preflight kan niet doorgaan
De pagina van de console voor een preflight-uitvoering die niet kan doorgaan. De falende controles komen eerst, elk in woorden benoemd met wat er is gevonden, en de installatie blijft geblokkeerd totdat ze slagen.
Drie kolommen. Links, "Werkstation van operator": een vak "nexusctl preflight --context --values" met twee uitvoeren eronder, "preflight-<time>.txt" en "preflight-<time>.json". Midden, "De installatie, niet geclaimd": een vak "nexus-keys" met het label "preflight-record, alleen nieuwste rapport". Een pijl van het linkervak naar nexus-keys heeft het label "pod exec met uw eigen clustertoegang (--record auto of always)". Rechts, "Browser, vóór aanmelding": een vak "Console-installatieprogramma, Preflight kan niet doorgaan". Een pijl van nexus-keys daarnaartoe heeft het label "GET /v1/installation/preflight". Onder het middelste vak staat een kleine opmerking: "na de claim: ROUTE_NOT_FOUND".
Waar één preflight-rapport naartoe gaat, van het werkstation van de operator naar de browser.

Toegang die de uitvoering nodig heeft

Preflight wordt uitgevoerd als uzelf, met uw kubeconfig. Het account moet het volgende kunnen lezen:

  • nodes, voor de controles op versie, gereedheid, resources en grafische voorzieningen;
  • opslagklassen en ingress-klassen;
  • Services in de ingress-namespace;
  • het TLS Secret in de installatie-namespace, wanneer de certificaatcontrole wordt uitgevoerd.

Wanneer een leesactie wordt geweigerd, vermeldt de rij could not read <what> (the cluster refused) en geeft de oplossing aan welke leestoegang moet worden verleend. De woorden bevatten nooit het adres van de server of de eigen fouttekst ervan, omdat het rapport vóór het aanmelden kan worden getoond. De overdracht heeft ook pods/exec op de nexus-keys-pods nodig; zonder dit slaat auto de bestanden op en drukt een waarschuwing af, en sluit always af met 2.

Wanneer preflight zelf niet kan worden uitgevoerd

Exitcode 2 betekent dat er geen rapport is gemaakt. Het bericht op standaardfout vermeldt waarom:

Bericht Wat te doen
--context is required: the kube context to check Voeg --context toe
--values is required: the values file the install will use Voeg --values toe
could not read the values file harrow-values.yaml Controleer het pad en de machtigingen van het bestand
preflight takes flags only Verwijder het losse argument
the report breaks its contract and was not printed, saved or handed over Een veld zou iets privés hebben bevat; meld dit aan Adverant met de vlaggen van de uitvoering
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to Installeer eerst, of gebruik --record auto
could not hand the report to this installation Controleer uw toegang om exec uit te voeren in nexus-keys

Een cluster waarvan de API niet kan worden bereikt, sluit ook af met 2. Herstel de kubeconfig of het netwerk en voer het opnieuw uit.

Zodra preflight eindigt met 0 failed, gaat u verder naar hoofdstuk 2.6, Community installeren op Kubernetes, om Community te installeren, of hoofdstuk 2.7, Enterprise installeren en een licentie toepassen, voor Enterprise.