Version 1.0.0-alpha.1senaste
Kapitel 2.5
Förkontroll med nexusctl
Varje kontroll som `nexusctl preflight` utför, vad var och en läser och hur den kan misslyckas, rapporten som skrivs ut och sparas, hur den rapporten når konsolens sida för förkontroll samt varje flagga.
Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

Vår första förkontroll (preflight) vid Harrow Port Authority underkändes i fyra kontroller, och två av dem hade kostat oss betydligt mer än en eftermiddag. Vi hade påbörjat vår values-fil genom att kopiera diagrammets exempel, och förkontrollen avvisade både det exempelbaserade installationsnamnet och exempel-nyckelförvaltaren (custodian). Ingen innehar den nyckelförvaltarens privata nyckel. En installation som förseglas mot den kan aldrig låsas upp efter en omstart av en nod. Förkontrollen fångade det på några sekunder, innan det fanns något att förlora.
nexusctl preflight läser ert kluster och er values-fil, skriver ut vad den hittade, sparar en rapport och ändrar ingenting i klustret. Kör den före varje installation och varje uppgradering. Detta kapitel behandlar varje kontroll den gör, rapportformatet, var rapporten hamnar samt flaggorna.
Drift
Förkontrollen behöver två saker: kube-kontexten för det kluster ni ska installera på, och den values-fil som installationen kommer att använda. Skriv er values-fil först; kapitel 2.6, Installera Community på Kubernetes, går igenom varje nyckel. Därefter:
nexusctl preflight --context harrow-prod --values harrow-values.yamlDen läser klustret via client-go med enbart get- och list-anrop. Om er tls.mode är existing, skapa namnrymden nexus och er Transport Layer Security (TLS) Secret innan ni kör den (kapitel 2.6, Installera Community på Kubernetes, steg 3), annars rapporterar certifikatkontrollen att er Secret saknas.
| Flagga | Vad den gör | Standardvärde |
|---|---|---|
--context <name> |
Den kube-kontext som ska kontrolleras. Obligatorisk | ingen |
--values <file> |
Den values-fil som installationen kommer att använda. Obligatorisk | ingen |
--namespace <name> |
Var Nexus installeras | nexus |
--release <version> |
Den version som kontrolleras | det medföljande diagrammets egen version |
--report-dir <dir> |
Var de två rapportfilerna sparas | den aktuella mappen |
--record <mode> |
auto, always eller never: huruvida rapporten ska lämnas över till denna installations nyckeltjänst, så att dess installationssida visar den |
auto |
--kubeconfig <file> |
Den kubeconfig som ska läsas | KUBECONFIG, sedan ~/.kube/config |
--ca-bundle <file> |
Era egna certifikatutfärdarcertifikat (CA), för en kedja som kontrollerna ska lita på | ingen |
--single-node |
Kontrollera en maskin för en enmaskinsinstallation (kapitel 2.8, Enmaskinsinstallationer) | av |
Versionens lägsta krav för Kubernetes är inte hårdkodat i nexusctl. Den läser den nedre gränsen för diagrammets egen kubeVersion från det diagram den bär med sig, så kontrollen och helm install kan aldrig vara oense.
Vad en körning skriver ut
Här är Harrows första körning, exakt som den skrevs 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 något underkänns kommer felen först, därefter varningarna och sist de godkända kontrollerna. Varje rad visar utfallet, kontrollens namn, vad som hittades och vad som krävs; varje rad som inte godkändes har en fix-rad under sig. De två sista raderna är sammanfattningen och rapportfilen.
Vi åtgärdade värdena, lade till de två posterna i Domain Name System (DNS), skapade vår Secret och körde 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örning utan fel listar kontrollerna under deras tre rubriker: Kluster, Nätverk samt Tid och nycklar. Varningar blockerar aldrig. Vi behöll grafikvarningen med flit: på detta uppkopplade pilotkluster använde Harrows assistent en värdbaserad modell med hamnens egen nyckel.
Avslutningskoder
| Kod | Betydelse |
|---|---|
0 |
Installationen kan fortsätta. Varningar blockerar inte |
1 |
Installationen är blockerad: minst en kontroll underkändes |
2 |
Förkontrollen kunde inte köras: kubeconfig, kontexten, values-filen eller klustrets applikationsprogrammeringsgränssnitt (API) kunde inte läsas, eller så var en flagga felaktig |
Skript bör läsa avslutningskoden (exit code), inte orden. Vårt skript kör förkontrollen som det första steget vid varje uppgradering och stannar vid allt annat än 0.
Kör nexusctl för den version ni uppgraderar till, inte den ni installerade med. Kraven kommer från det diagram den bär med sig, så en nyare version kan höja minimikravet för Kubernetes eller kräva mer minne, och endast dess egen nexusctl känner till detta. --release ändrar vilken version rapporten namnger; den ändrar inte vilket diagrams regler som tillämpas. På Harrow sparar vi varje versions nexusctl bredvid dess diagram i ändringsloggen, så att en återställning kontrolleras av det verktyg som matchar den.
Varje kontroll
Det finns elva kontroller. Tio av dem genererar en rad vardera; adresskontrollen genererar en rad per värd, så en fullständig körning har tretton rader. Nio kontroller måste godkännas, och en avvikelse är ett fel. Två – grafiknoderna och certifikatet – bör godkännas, och en avvikelse är en varning. Den sista kolumnen är den kravtext som varje rad tar med sig in i rapporten; CPU i den står för centralprocessor (central processing unit).
| Kontroll-id | Avsnitt | Måste godkännas | Krav som skrivs ut |
|---|---|---|---|
kubernetes-version |
cluster | ja | Kubernetes 1.33 eller senare |
nodes-ready |
cluster | ja | Varje nod redo |
storage-class |
cluster | ja | En lagringsklass för data |
resources |
cluster | ja | Tillräckligt med CPU och minne för versionen |
graphics-nodes |
cluster | nej | Grafiknoder |
ingress-class |
network | ja | En ingressklass för de tre adresserna |
ingress-ports |
network | ja | Ingress-kontrollern öppen på portarna 80 och 443 |
address-console, address-api, address-auth |
network | ja | Adressen för console, api eller auth kan slås upp i DNS |
certificate |
network | nej | Certifikatet giltigt i minst 30 dagar till |
custodians |
time-and-keys | ja | De personer som innehar denna installations återställningsnycklar |
installation-name |
time-and-keys | ja | Denna installations eget permanenta namn |
kubernetes-version
Läser API-serverns version och jämför den med diagrammets lägsta krav. Den hittar till exempel 1.33.6+k3s1. Under 1.33 underkänns den med åtgärden upgrade the cluster to 1.33 or later. Om versionssträngen inte är en som nexusctl kan läsa, underkänns den hellre än att gissa.
nodes-ready
Listar noderna och räknar de vars Ready-villkor är sant, som 3 of 3. Varje nod som inte är redo namnges, och åtgärden uppmanar er att få den tillbaka till Ready och läsa dess villkor. Ett kluster helt utan noder underkänns med en ledtråd om att kontexten kan peka på fel kluster.
storage-class
Om era värden anger storage.className, slår kontrollen upp den klassen och underkänns med <name> does not exist när den saknas. Om de inte gör det, letar den efter en klass markerad som standard (default) och rapporterar den som local-path (default). Utan standardklass underkänns den med none marked default, och kravkolumnen anger varför det spelar roll: the database cannot claim a disk. Om två klasser är markerade som standard, ger klustret ett nytt anspråk (claim) till den nyaste, så det är den som rapporteras.
resources
Räknar ut vad releasen kräver utifrån chartet och era värden, och summerar sedan de allokerbara kärnorna för centralprocessorn (CPU) och minnet för varje nod som är Ready, inte avspärrad (cordoned), och inte bär någon NoSchedule- eller NoExecute-taint. Chartets poddar har inga tolerations, så en nod med taint kan inte köra dem och räknas inte. Ett kluster med för lite resurser underkänns med det exakta underskottet, 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 avrundas uppåt och tillgång nedåt, så kontrollen ger aldrig en förskönad bild.
graphics-nodes
Letar efter en Ready-nod med en grafikprocessor (GPU) som den kan allokera, nvidia.com/gpu. Om ingen finns varnar den: the assistant will need a hosted model. Förkontrollen behandlar det som ett råd och blockerar aldrig på grund av det, eftersom assistenten kan svara via en värdbaserad modell för artificiell intelligens (AI) istället. Kapitel 2.14, AI-leverantörer och modeller, behandlar båda alternativen.
ingress-class
Om ingress.className är angiven, slår kontrollen upp den klassen. Om inte, letar den efter exakt en klass markerad som standard. Två klasser markerade som standard underkänns också, eftersom API-servern då avvisar en Ingress utan klass. Kontrollen hoppas över, och dess rad utelämnas, när ingress.enabled är false.
ingress-ports
Letar i den namnrymd som namnges av networkPolicy.ingressNamespace (som standard kube-system, där k3s kör Traefik) efter en LoadBalancer- eller NodePort-Service som exponerar både 80 och 443. Diagrammets nätverkspolicy tillåter endast den namnrymden att nå de tre publika Services, så en ingress-kontroller någon annanstans skulle inte kunna betjäna Nexus även om den lyssnade. Åtgärden nämner båda utvägarna: exponera kontrollern där, eller ställ in networkPolicy.ingressNamespace till var den körs. Hoppas över när ingress.enabled är false.
address
Slår upp hosts.console, hosts.api och hosts.auth från er arbetsstation, fem sekunder vardera, och skriver ut en rad per värd. En värd utan post underkänns med <host> → no record. En oinställd värd underkänns med hosts.<key> is not set. När ett namn har flera adresser visar raden den första, IPv4 före IPv6, och hur många fler det finns.
certificate
Körs endast när tls.mode är existing och tls.existingSecret namnger en Secret; med cert-manager eller none finns det inget eget certifikat att läsa, och raden utelämnas. Den läser tls.crt från denna Secret i installationsnamnrymden och ingenting annat. Ett certifikat som är giltigt i 30 dagar eller mer godkänns som ends 3 Nov 2027. Ett som går ut tidigare varnar ends in 9 days; ett som redan har gått ut varnar ended 4 days ago. En saknad Secret, eller en utan certifikat i sig, varnar med åtgärden.
custodians
Läser keys.custody.recipients. Om inga finns underkänns den med koden KEYS_CUSTODIAN_MISSING. Om någon mottagare är exempel-nyckelförvaltaren från diagrammets egna values-filer, underkänns den med KEYS_CUSTODIAN_EXAMPLE, eftersom ingen innehar den nyckeln och installationens återställningsnycklar skulle förseglas mot ingen alls. Ett godkännande skriver ut antalet, såsom 3 custodians.
installation-name
Läser keys.installationName. Om det inte är inställt, underkänns den med INSTALLATION_NAME_MISSING. Om det är inställt på exempelnamnet från diagrammets values-filer, underkänns den med INSTALLATION_NAME_EXAMPLE. Ett godkännande skriver ut namnet. Kravkolumnen anger varför denna är viktigare än de flesta: the first key-store bootstrap mints the installation identity under it, permanently.
De två sista kontrollerna rapporterar exakt de koder som diagrammet självt använder för att avvisa en installation. Förkontrollen berättar det bara för er först, innan Helm har skapat någonting.
Rapportfilerna
Varje körning sparar två filer i --report-dir, namngivna efter tiden då den kördes: preflight-2026-11-12-0902.txt, raderna så som de skrevs ut utan färgkoder, och preflight-2026-11-12-0902.json, samma körning i ett fast format som ett program kan läsa. Terminalutskriften och de sparade raderna kommer från samma lista, så de skiljer sig aldrig åt.
JSON-rapporten följer schemat nexus.preflight/v1:
| Fält | Vad den innehåller |
|---|---|
schema |
Exakt nexus.preflight/v1 |
tool |
Ett objekt: name (nexusctl) och version |
release |
Den kontrollerade versionen |
ran_at |
När den kördes, i koordinerad universell tid (UTC) |
context |
Kube-kontextens namn |
values |
Endast values-filens basnamn |
read_only |
Alltid true |
checks |
En post per rad: id, section, name, requirement, must_pass, outcome (pass, warn eller fail), found, needs, fix, och vid en avvikelse med en maskinorsak, code |
counts |
passed, warnings och failed |
can_install |
true när ingenting underkändes |
report_file |
Namnet på .txt-filen |
transcript |
Ett objekt: title (nexusctl preflight) och lines, varje rad med sin kind (prompt, ok, warn, bad, note, out eller blank), sin text och at, och ibland marks |
Rapporten är utformad för att visas innan någon loggar in, så den innehåller inget användarnamn, inget värdnamn för arbetsstationen, ingen filsökväg, ingen token och ingenting från er kubeconfig. values är ett basnamn och context är kontextens namn. Om en körnings rapport skulle bryta mot någon av dessa regler, vägrar nexusctl att skriva ut, spara eller lämna över den, och meddelar detta. En rapport är högst 256 KiB, med högst 64 kontroller och 512 tecken i något enskilt textfält.
Hur rapporten når konsolen
Förkontrollens enda skrivåtgärd är den färdiga rapporten, som lämnas över till installationens nyckeltjänst, nexus-keys, så att konsolens installationsprogram kan visa den på sin förkontrollsida innan någon har gjort anspråk på installationen. --record avgör om ett försök ska göras:
--record |
Vad som händer |
|---|---|
auto |
Lämnar över rapporten endast när namnrymden har en nexus-keys Deployment |
always |
Kräver överlämning; förkontrollen avslutas med 2 om det inte finns något att lämna över den till |
never |
Lämnar inte över den |
Så en körning före den första installationen har ingenting att lämna över till, och behåller rapporten på er arbetsstation. En körning efter installationen och före anspråket registrerar den.
Överlämningen använder er egen klusteråtkomst. nexusctl kör /app/nexus-keys preflight-record i keys-containern på en redo nexus-keys-podd och skickar rapporten via standardinmatning (standard input). Det är detsamma som:
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonNyckeltjänsten kontrollerar rapporten mot samma regler som nexusctl tillämpar och behåller endast den senaste. När den har lämnats över, skriver nexusctl ut ytterligare en rad som anger detta, och den sparade JSON-filen får en note som registrerar överlämningen.
Konsolens installationsprogram läser den från nyckeltjänstens publika rutt GET /v1/installation/preflight. Den rutten svarar endast medan installationen är utan anspråk: innan någon rapport har registrerats svarar den 404 RECORD_NOT_FOUND, och när någon väl gör anspråk på installationen svarar den ROUTE_NOT_FOUND för gott, precis som anspråksrutten gör. En rapport som lämnas över efter anspråket avvisas med INSTALLATION_CLAIMED.
I konsolen visas en körning med fel som "Preflight cannot continue": antalet underkända, varningar och godkända, därefter varje kontroll grupperad under "Must pass" och "Should pass", med de som inte godkändes först och de funna värdena bredvid var och en. En körning utan fel får inte den sidan; konsolen går direkt vidare till anspråket (kapitel 2.12, Den första körningen).
Behörigheter som körningen kräver
Förkontrollen körs som er, med er kubeconfig. Kontot behöver läsbehörighet för:
- noder, för kontrollerna av version, beredskap, resurser och grafik;
- lagringsklasser och ingressklasser;
- Services i ingress-namnrymden;
- TLS Secret i installationsnamnrymden, när certifikatkontrollen körs.
När en läsning nekas, anger raden could not read <what> (the cluster refused), och åtgärden anger vilken läsbehörighet som ska beviljas. Orden innehåller aldrig serverns adress eller dess egen feltext, eftersom rapporten kan komma att visas före inloggning. Överlämningen behöver också pods/exec på nexus-keys-poddarna; utan det sparar auto filerna och skriver ut en varning, och always avslutas med 2.
När själva förkontrollen inte kan köras
Avslutningskod 2 betyder att ingen rapport skapades. Meddelandet på standardfelutmatningen (standard error) anger varför:
| Meddelande | Vad du ska göra |
|---|---|
--context is required: the kube context to check |
Lägg till --context |
--values is required: the values file the install will use |
Lägg till --values |
could not read the values file harrow-values.yaml |
Kontrollera sökvägen och filens behörigheter |
preflight takes flags only |
Ta bort det överflödiga argumentet |
the report breaks its contract and was not printed, saved or handed over |
Ett fält skulle ha innehållit något privat; rapportera det till Adverant med körningens flaggor |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
Installera först, eller använd --record auto |
could not hand the report to this installation |
Kontrollera er behörighet att köra exec in i nexus-keys |
Ett kluster vars API inte kan nås avslutas också med 2. Åtgärda er kubeconfig eller nätverket, och kör den igen.
När förkontrollen avslutas med 0 failed, gå vidare till kapitel 2.6, Installera Community på Kubernetes, för att installera Community, eller kapitel 2.7, Installera Enterprise och tillämpa en licens, för Enterprise.

