Logi sisseBroneerige tutvustus

Peatükk 2.5

Eelkontroll tööriistaga nexusctl

Iga kontroll, mille `nexusctl preflight` teeb, mida igaüks neist loeb ja kuidas see ebaõnnestub, aruanne, mille see kuvab ja salvestab, kuidas see aruanne jõuab konsooli eelkontrolli lehele, ning iga lipp.

Selle lehe tõlkis AI ingliskeelsest originaalist. Kui miski jääb ebaselgeks, võtke aluseks ingliskeelne leht. Lugege seda lehte inglise keeles

16 minutit lugemist

Meie esimene eelkontroll Harrow Port Authoritys ei läbinud nelja kontrolli ning kaks neist oleksid meile maksma läinud palju rohkem kui ühe pärastlõuna. Olime alustanud väärtuste faili diagrammi näidise kopeerimisega ning eelkontroll lükkas tagasi nii näidise paigaldusnime kui ka näidise võtmehoidja. Kellelgi pole selle võtmehoidja privaatvõtit. Sellega pitseeritud paigaldust ei saa pärast sõlme taaskäivitamist enam kunagi lahti pitseerida. Eelkontroll tabas selle mõne sekundiga, enne kui üldse eksisteeris midagi, mida kaotada.

nexusctl preflight loeb teie klastrit ja väärtuste faili, kuvab leitu, salvestab aruande ega muuda klastris midagi. Käivitage see enne iga paigaldust ja iga uuendust. See peatükk käsitleb kõiki tehtavaid kontrolle, aruande vormingut, aruande asukohta ja lippe.

Selle käitamine

Eelkontroll vajab kahte asja: selle klastri kube-konteksti, kuhu te paigaldate, ja väärtuste faili, mida paigaldus kasutab. Kirjutage esmalt väärtuste fail; peatükk 2.6, Community paigaldamine Kubernetesele, käib läbi iga võtme. Seejärel:

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

See loeb klastrit läbi client-go ainult get- ja list-kutsetega. Kui teie tls.mode on existing, looge enne selle käivitamist nexus nimeruum ja transpordikihi turbe (TLS) Secret (peatükk 2.6, Community paigaldamine Kubernetesele, 3. samm), muidu teatab sertifikaadikontroll, et Secret on puudu.

Lipp Mida see teeb Vaikeväärtus
--context <name> Kontrollitav kube-kontekst. Kohustuslik puudub
--values <file> Väärtuste fail, mida paigaldus kasutab. Kohustuslik puudub
--namespace <name> Kuhu Nexus paigaldatakse nexus
--release <version> Kontrollitav väljalase kaasasoleva diagrammi enda versioon
--report-dir <dir> Kuhu kaks aruandefaili salvestatakse praegune kaust
--record <mode> auto, always või never: kas edastada aruanne selle paigalduse võtmeteenusele, et selle paigaldusleht seda näitaks auto
--kubeconfig <file> Loetav kubeconfig KUBECONFIG, seejärel ~/.kube/config
--ca-bundle <file> Teie enda sertifitseerimiskeskuse (CA) sertifikaadid ahela jaoks, mida kontrollid peaksid usaldama puudub
--single-node Ühe masina kontrollimine ühe masina paigalduse jaoks (peatükk 2.8, Ühe masina paigaldused) väljas

Väljalaske Kubernetese alampiir ei ole nexusctl sisse kirjutatud. See loeb kaasasolevalt diagrammilt selle enda kubeVersion alampiiri, mistõttu kontroll ja helm install ei saa kunagi eriarvamusele jääda.

Mida käivitamine kuvab

Siin on Harrow' esimene käivitus nii, nagu see kuvati:

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

Kui miski ebaõnnestub, kuvatakse esmalt tõrked, seejärel hoiatused ja siis läbitud kontrollid. Iga rida näitab tulemust, kontrolli nime, leitut ja nõutavat; iga rea all, mis kontrolli ei läbinud, on fix rida. Viimased kaks rida on kokkuvõte ja aruandefail.

Parandasime väärtused, lisasime kaks domeeninimesüsteemi (DNS) kirjet, lõime Secreti ja käivitasime selle uuesti:

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

Ilma tõrgeteta käivitus loetleb kontrollid nende kolme pealkirja all: Klaster, Võrk ning Aeg ja võtmed. Hoiatused ei blokeeri kunagi. Jätsime graafika hoiatuse meelega alles: selles ühendatud pilootklastris kasutas Harrow' assistent sadama enda võtmega majutatud mudelit.

Enne paigaldamist
Enne paigaldamist
Eelkontroll operaatori terminalis, loendurid selle kõrval. Pange tähele, et iga hoiatuse all on kuvatud selle parandus ning käivitus ütleb selgelt, et see ei muutnud klastris midagi.

Väljumiskoodid

Kood Tähendus
0 Paigaldusega võib jätkata. Hoiatused ei blokeeri
1 Paigaldus on blokeeritud: vähemalt üks kontroll ebaõnnestus
2 Eelkontrolli ei saanud käivitada: kubeconfig-i, konteksti, väärtuste faili või klastri rakendusliidest (API) ei õnnestunud lugeda või mõni lipp oli vale

Skriptid peaksid lugema väljumiskoodi, mitte sõnu. Meie oma käivitab eelkontrolli iga uuenduse esimese sammuna ja peatub kõige muu kui 0 korral.

Käivitage selle väljalaske nexusctl, millele te üle lähete, mitte see, millega te paigaldasite. Nõuded pärinevad kaasasolevalt diagrammilt, seega võib uuem väljalase tõsta Kubernetese alampiiri või küsida rohkem mälu, ning seda teab ainult tema enda nexusctl. --release muudab versiooni, mida aruanne nimetab; see ei muuda, millise diagrammi reegleid rakendatakse. Harrow's hoiame iga väljalaske nexusctl muudatuste kirjes selle diagrammi kõrval, nii et tagasipööramist kontrollib sellega sobiv tööriist.

Iga kontroll

Kontrolle on üksteist. Kümme neist annavad igaüks ühe rea; aadressikontroll annab ühe rea iga hosti kohta, seega on täielikul käivitusel kolmteist rida. Üheksa kontrolli peavad läbi minema ja puudujääk on tõrge. Kaks – graafikasõlmed ja sertifikaat – peaksid läbi minema ja puudujääk on hoiatus. Viimane veerg on nõude tekst, mille iga rida aruandesse kannab; CPU tähendab selles keskprotsessorit.

Kontrolli ID Jaotis Peab läbima Kuvatav nõue
kubernetes-version cluster jah Kubernetes 1.33 või uuem
nodes-ready cluster jah Iga sõlm on valmis
storage-class cluster jah Salvestusklass andmete jaoks
resources cluster jah Piisavalt CPU-d ja mälu väljalaske jaoks
graphics-nodes cluster ei Graafikasõlmed
ingress-class network jah Ingress-klass kolme aadressi jaoks
ingress-ports network jah Ingress-kontroller on avatud portidel 80 ja 443
address-console, address-api, address-auth network jah Konsooli, api või auth aadress lahendub DNS-is
certificate network ei Sertifikaat kehtib veel 30 päeva
custodians time-and-keys jah Inimesed, kelle käes on selle paigalduse taastevõtmed
installation-name time-and-keys jah Selle paigalduse enda püsiv nimi

kubernetes-version

Loeb API-serveri versiooni ja võrdleb seda diagrammi alampiiriga. See leiab näiteks 1.33.6+k3s1. Alla 1.33 ebaõnnestub see parandusega upgrade the cluster to 1.33 or later. Kui versioonistring ei ole selline, mida nexusctl lugeda oskab, siis see ebaõnnestub, mitte ei hakka oletama.

nodes-ready

Loetleb sõlmed ja loendab need, mille Ready tingimus on tõene, kujul 3 of 3. Iga sõlm, mis pole valmis, nimetatakse ära, ning parandus käsib teil viia see tagasi olekusse Ready ja lugeda selle tingimusi. Täiesti ilma sõlmedeta klaster ebaõnnestub vihjega, et kontekst võib viidata valele klastrile.

storage-class

Kui teie väärtused määravad storage.className, otsib kontroll seda klassi ja ebaõnnestub teatega <name> does not exist, kui see puudub. Kui ei määra, otsib see vaikimisi klassiks märgitud klassi ja teatab sellest kui local-path (default). Vaikeklassi puudumisel ebaõnnestub see teatega none marked default ja vajaduste veerg ütleb, miks see on oluline: the database cannot claim a disk. Kui kaks klassi on märgitud vaikeklassiks, annab klaster uuele nõudele uusima, seega teatatakse just sellest.

resources

Arvutab diagrammi ja teie väärtuste põhjal välja, mida väljalase küsib, ning liidab seejärel kokku iga sellise sõlme eraldatavad keskprotsessori (CPU) tuumad ja mälu, mis on olekus Ready, ei ole piiratud (cordoned) ega kanna märget (taint) NoSchedule või NoExecute. Diagrammi pod-idel pole toleratsioone, mistõttu märkega sõlm ei saa neid käitada ega lähe arvesse. Ressursipuuduses klaster ebaõnnestub täpse puudujäägiga, näiteks add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Vajadused ümardatakse üles ja pakkumine alla, nii et kontroll ei meelita teid kunagi.

graphics-nodes

Otsib olekus Ready sõlme, millel on graafikaprotsessor (GPU), mida see saab eraldada, nvidia.com/gpu. Kui ühtegi pole, annab see hoiatuse: the assistant will need a hosted model. Eelkontroll käsitleb seda soovitusena ega blokeeri selle tõttu kunagi, sest assistent saab vastata hoopis majutatud AI-mudeli kaudu. Peatükk 2.14, AI pakkujad ja mudelid, käsitleb mõlemat teed.

ingress-class

Kui ingress.className on määratud, otsib kontroll seda klassi. Kui ei ole, otsib see täpselt ühte vaikeklassiks märgitud klassi. Kaks vaikeklassiks märgitud klassi põhjustavad samuti tõrke, sest API-server keeldub sel juhul ilma klassita Ingressist. Kontroll jäetakse vahele ja selle rida jäetakse välja, kui ingress.enabled on false.

ingress-ports

Otsib nimeruumist, mille nimetab networkPolicy.ingressNamespace (vaikimisi kube-system, kus k3s käitab Traefikut), ühte LoadBalancer või NodePort Service'it, mis avab nii pordi 80 kui ka 443. Diagrammi võrgupoliitika lubab ainult sellel nimeruumil jõuda kolme avaliku Service'ini, seega ei saaks kuskil mujal asuv ingress-kontroller Nexust teenindada isegi siis, kui see kuulaks. Parandus nimetab mõlemad väljapääsud: avage kontroller seal või määrake networkPolicy.ingressNamespace kohta, kus see töötab. Jäetakse vahele, kui ingress.enabled on false.

address

Otsib teie tööjaamast üles hosts.console, hosts.api ja hosts.auth, igaühte viis sekundit, ja kuvab ühe rea iga hosti kohta. Ilma kirjeta host ebaõnnestub teatega <host> → no record. Määramata host ebaõnnestub teatega hosts.<key> is not set. Kui nimel on mitu aadressi, näitab rida esimest, IPv4 enne IPv6, ja seda, mitu tükki neid veel on.

certificate

Käivitatakse ainult siis, kui tls.mode on existing ja tls.existingSecret nimetab Secreti; cert-manager või none korral pole ühtegi teie sertifikaati, mida lugeda, ja rida jäetakse välja. See loeb paigalduse nimeruumis olevast Secretist tls.crt ja mitte midagi muud. Sertifikaat, mis kehtib veel 30 päeva või kauem, läbib kontrolli kui ends 3 Nov 2027. Varem lõppev sertifikaat hoiatab ends in 9 days; juba lõppenud sertifikaat hoiatab ended 4 days ago. Puuduv Secret või selline, milles pole sertifikaati, annab hoiatuse koos parandusega.

custodians

Loeb keys.custody.recipients. Kui ühtegi pole, ebaõnnestub see koodiga KEYS_CUSTODIAN_MISSING. Kui mõni saaja on näidis-võtmehoidja diagrammi enda väärtuste failidest, ebaõnnestub see koodiga KEYS_CUSTODIAN_EXAMPLE, sest selle võtme omanikku pole olemas ja paigalduse taastevõtmed pitseeritaks mitte kellelegi. Läbimine kuvab arvu, näiteks 3 custodians.

installation-name

Loeb keys.installationName. Kui see on määramata, ebaõnnestub see koodiga INSTALLATION_NAME_MISSING. Kui see on määratud diagrammi väärtuste failidest pärit näidisnimeks, ebaõnnestub see koodiga INSTALLATION_NAME_EXAMPLE. Läbimine kuvab nime. Vajaduste veerg ütleb, miks see on olulisem kui enamik teisi: the first key-store bootstrap mints the installation identity under it, permanently.

Viimased kaks kontrolli teatavad täpselt needsamad koodid, millega diagramm ise paigaldusest keeldub. Eelkontroll lihtsalt ütleb teile seda esimesena, enne kui Helm on midagi loonud.

Aruandefailid

Iga käivitus salvestab kausta --report-dir kaks faili, mis on nimetatud käivitamise aja järgi: preflight-2026-11-12-0902.txt, kuvatud read ilma värvikoodideta, ja preflight-2026-11-12-0902.json, sama käivitus kindlas vormingus, mida programm saab lugeda. Terminali väljund ja salvestatud read pärinevad samast loendist, seega ei erine need kunagi.

JSON-aruanne järgib skeemi nexus.preflight/v1:

Väli Mida see sisaldab
schema Täpselt nexus.preflight/v1
tool Objekt: name (nexusctl) ja version
release Kontrollitud väljalase
ran_at Millal see käivitati, maailmaajas (UTC)
context Kube-konteksti nimi
values Ainult väärtuste faili baasnimi
read_only Alati true
checks Üks kirje rea kohta: id, section, name, requirement, must_pass, outcome (pass, warn või fail), found, needs, fix ja masinapoolse põhjusega puudujäägi korral code
counts passed, warnings ja failed
can_install true, kui miski ei ebaõnnestunud
report_file Faili .txt nimi
transcript Objekt: title (nexusctl preflight) ja lines, iga rida oma kind-ga (prompt, ok, warn, bad, note, out või blank), oma text ja at-ga ning mõnikord marks-ga

Aruanne on loodud kuvamiseks enne kellegi sisselogimist, seega ei sisalda see kasutajanime, tööjaama hostinime, failiteed, luba (token) ega midagi teie kubeconfig-ist. values on baasnimi ja context on konteksti nimi. Kui käivituse aruanne rikuks mõnda neist reeglitest, keeldub nexusctl seda kuvamast, salvestamast või üle andmast ning ütleb seda. Aruanne on kuni 256 KiB, selles on kuni 64 kontrolli ja üheski tekstiväljas pole rohkem kui 512 tähemärki.

Kuidas aruanne konsooli jõuab

Eelkontrolli ainus kirjutamistoiming on valmis aruanne, mis antakse üle paigalduse võtmeteenusele nexus-keys, et konsooli paigaldaja saaks seda näidata oma eelkontrolli lehel enne, kui keegi on paigalduse enda nimele võtnud. --record otsustab, kas proovida:

--record Mis juhtub
auto Annab aruande üle ainult siis, kui nimeruumis on nexus-keys Deployment
always Nõuab tungivalt; eelkontroll väljub koodiga 2, kui pole midagi, millele seda üle anda
never Ei anna seda üle

Seega pole enne esimest paigaldust toimuval käivitusel midagi, millele aruannet üle anda, ja see hoiab aruannet teie tööjaamas. Pärast paigaldust ja enne omandamist toimuv käivitus salvestab selle.

Üleandmine kasutab teie enda klastripääsu. nexusctl käivitab valmisolekus nexus-keys pod-i konteineris keys käsu /app/nexus-keys preflight-record ja edastab aruande standardsisendis. See on sama mis:

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

Võtmeteenus kontrollib aruannet samade reeglite alusel, mida rakendab nexusctl, ja hoiab alles ainult viimase. Kui see on üle antud, kuvab nexusctl veel ühe rea, mis seda ütleb, ja salvestatud JSON saab juurde välja note, mis registreerib üleandmise.

Konsooli paigaldaja loeb seda võtmeteenuse avalikult marsruudilt GET /v1/installation/preflight. See marsruut vastab ainult seni, kuni paigaldus on omandamata: enne ühegi aruande salvestamist vastab see 404 RECORD_NOT_FOUND, ja kui keegi võtab paigalduse enda nimele, vastab see lõplikult ROUTE_NOT_FOUND, täpselt nagu omandamise marsruutki. Pärast omandamist üle antud aruanne lükatakse tagasi teatega INSTALLATION_CLAIMED.

Konsoolis ilmub tõrgetega käivitus kui „Eelkontroll ei saa jätkata“: ebaõnnestunud, hoiatustega ja läbitud kontrollide arvud, seejärel iga kontroll rühmitatuna pealkirjade „Peab läbima“ ja „Peaks läbima“ alla, kusjuures esimesena on need, mis läbi ei läinud, ja igaühe kõrval on leitud sõnad. Ilma tõrgeteta käivitus seda lehte ei saa; konsool liigub otse edasi omandamise juurde (peatükk 2.12, Esimene käivitus).

Eelkontroll ei saa jätkata
Eelkontroll ei saa jätkata
Konsooli leht eelkontrolli käivituse jaoks, mis ei saa jätkata. Ebaõnnestunud kontrollid on esimesed, igaüks nimetatud sõnadega koos leituga, ning paigaldus jääb blokeerituks, kuni need läbi lähevad.
Kolm veergu. Vasakul, „Operaatori tööjaam“: kast „nexusctl preflight --context --values“, mille all on kaks väljundit, „preflight-<time>.txt“ ja „preflight-<time>.json“. Keskel, „Paigaldus, omandamata“: kast „nexus-keys“ sildiga „preflight-record, ainult viimane aruanne“. Nool vasakpoolsest kastist kasti nexus-keys juurde kannab silti „pod exec teie enda klastripääsuga (--record auto või always)“. Paremal, „Brauser, enne sisselogimist“: kast „Konsooli paigaldaja, Eelkontroll ei saa jätkata“. Nool kastist nexus-keys selle juurde kannab silti „GET /v1/installation/preflight“. Keskmise kasti all on väike märkus „pärast omandamist: ROUTE_NOT_FOUND“.
Kuhu üks eelkontrolli aruanne liigub, operaatori tööjaamast brauserisse.

Juurdepääs, mida käivitamine vajab

Eelkontroll töötab teie nimel, teie kubeconfig-iga. Konto peab saama lugeda:

  • sõlmi – versiooni, valmisoleku, ressursside ja graafika kontrollimiseks;
  • salvestusklasse ja ingress-klasse;
  • Service'eid ingressi nimeruumis;
  • TLS Secretit paigalduse nimeruumis, kui sertifikaadikontroll käivitatakse.

Kui lugemisest keeldutakse, ütleb rida could not read <what> (the cluster refused) ja parandus ütleb, milline lugemisõigus tuleb anda. Sõnad ei sisalda kunagi serveri aadressi ega selle enda veateksti, sest aruannet võidakse näidata enne sisselogimist. Üleandmine vajab ka õigust pods/exec pod-idel nexus-keys; ilma selleta salvestab auto failid ja kuvab hoiatuse ning always väljub koodiga 2.

Kui eelkontroll ise ei saa käivituda

Väljumiskood 2 tähendab, et aruannet ei koostatud. Teade standardveaväljundis ütleb, miks:

Teade Mida teha
--context is required: the kube context to check Lisage --context
--values is required: the values file the install will use Lisage --values
could not read the values file harrow-values.yaml Kontrollige failiteed ja faili õigusi
preflight takes flags only Eemaldage üleliigne argument
the report breaks its contract and was not printed, saved or handed over Väli oleks sisaldanud midagi privaatset; teatage sellest Adverantile koos käivituse lippudega
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to Paigaldage esmalt või kasutage --record auto
could not hand the report to this installation Kontrollige oma õigust käivitada exec pod-is nexus-keys

Klaster, mille API-ni ei saada ühendust, väljub samuti koodiga 2. Parandage kubeconfig või võrk ja käivitage see uuesti.

Kui eelkontroll lõpeb koodiga 0 failed, minge edasi peatükki 2.6, Community paigaldamine Kubernetesele, et paigaldada Community, või peatükki 2.7, Enterprise'i paigaldamine ja litsentsi rakendamine, Enterprise'i jaoks.