Logga inBoka en genomgång

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

16 minuters läsning

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

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

Innan ni installerar
Innan ni installerar
Förkontroll i operatörens terminal, med antalen bredvid. Lägg märke till att varje varning har sin åtgärd utskriven under sig, och att körningen tydligt anger att den inte ändrade någonting i klustret.

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

Nyckeltjä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).

Förkontrollen kan inte fortsätta
Förkontrollen kan inte fortsätta
Konsolens sida för en förkontrollkörning som inte kan fortsätta. De underkända kontrollerna kommer först, var och en namngiven i ord med vad som hittades, och installationen förblir blockerad tills de godkänns.
Tre kolumner. Till vänster, "Operatörens arbetsstation": en ruta "nexusctl preflight --context --values" med två utdata under sig, "preflight-<time>.txt" och "preflight-<time>.json". I mitten, "Installationen, utan anspråk": en ruta "nexus-keys" med etiketten "preflight-record, endast senaste rapporten". En pil från den vänstra rutan till nexus-keys har etiketten "pod exec med er egen klusteråtkomst (--record auto eller always)". Till höger, "Webbläsare, före inloggning": en ruta "Konsolens installationsprogram, Preflight cannot continue". En pil från nexus-keys till den har etiketten "GET /v1/installation/preflight". Under mittenrutan står en liten notering: "efter anspråket: ROUTE_NOT_FOUND".
Vägen för en förkontrollrapport, från operatörens arbetsstation till webbläsaren.

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.