PrijavaZakažite brifing

Poglavlje 2.5

Predinstalaciona provera pomoću alata nexusctl

Svaka provera koju vrši `nexusctl preflight`, šta svaka od njih čita i kako ne uspeva, izveštaj koji ispisuje i čuva, kako taj izveštaj stiže do stranice preflight u konzoli i svaka zastavica.

Ovu stranicu je sa engleskog originala prevela AI tehnologija. Ako nešto nije jasno, merodavna je stranica na engleskom. Pročitajte ovu stranicu na engleskom

16 min čitanja

Naša prva provera pre instalacije u Harrow Port Authority nije prošla četiri provere, a dve od njih bi nas koštale mnogo više od jednog popodneva. Fajl sa vrednostima započeli smo kopiranjem primera iz chart-a, a provera pre instalacije odbila je i primer naziva instalacije i primer čuvara ključeva. Niko ne poseduje privatni ključ tog čuvara. Instalacija zapečaćena za njega nikada ne može biti otpečaćena nakon ponovnog pokretanja čvora. Provera pre instalacije je to otkrila za nekoliko sekundi, pre nego što je postojalo išta što bi se moglo izgubiti.

nexusctl preflight čita vaš klaster i vaš fajl sa vrednostima, ispisuje šta je pronašao, čuva izveštaj i ne menja ništa na klasteru. Pokrenite ga pre svake instalacije i svake nadogradnje. Ovo poglavlje obuhvata svaku proveru koju izvršava, format izveštaja, mesto na koje se izveštaj čuva i opcije.

Održavanje i rad

Za proveru pre instalacije potrebne su dve stvari: kube kontekst klastera na koji ćete instalirati i fajl sa vrednostima koji će instalacija koristiti. Najpre napišite fajl sa vrednostima; poglavlje 2.6, Instaliranje izdanja Community na Kubernetes, objašnjava svaki ključ. Zatim:

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

Klaster čita putem client-go isključivo pozivima get i list. Ako je vaš tls.mode existing, napravite namespace nexus i Transport Layer Security (TLS) Secret pre pokretanja (poglavlje 2.6, Instaliranje izdanja Community na Kubernetes, korak 3), u suprotnom će provera sertifikata prijaviti da Secret nedostaje.

Opcija Šta radi Podrazumevano
--context <name> Kube kontekst koji se proverava. Obavezno nema
--values <file> Fajl sa vrednostima koji će instalacija koristiti. Obavezno nema
--namespace <name> Gde se Nexus instalira nexus
--release <version> Izdanje koje se proverava sopstvena verzija priloženog chart-a
--report-dir <dir> Gde se čuvaju dva fajla izveštaja trenutna fascikla
--record <mode> auto, always ili never: da li izveštaj predati servisu za ključeve ove instalacije, kako bi ga prikazala njena stranica instalera auto
--kubeconfig <file> Kubeconfig koji se čita KUBECONFIG, zatim ~/.kube/config
--ca-bundle <file> Vaši sopstveni sertifikati sertifikacionog tela (CA), za lanac kojem provere treba da veruju nema
--single-node Provera jedne mašine za instalaciju na jednoj mašini (poglavlje 2.8, Instalacije na jednoj mašini) isključeno

Minimalna verzija Kubernetes za izdanje nije upisana u nexusctl. On čita donju granicu sopstvenog kubeVersion chart-a iz chart-a koji nosi, tako da se provera i helm install nikada ne mogu razilaziti.

Šta izvršavanje ispisuje

Evo prvog pokretanja u Harrow, onako kako je ispisano:

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

Kada nešto ne prođe, najpre se prikazuju neuspesi, zatim upozorenja, pa uspešne provere. Svaki red prikazuje ishod, naziv provere, šta je pronađeno i šta je potrebno; ispod svakog reda koji nije prošao nalazi se red fix. Poslednja dva reda su rezime i fajl izveštaja.

Ispravili smo vrednosti, dodali dva zapisa sistema imena domena (DNS), napravili Secret i ponovo pokrenuli proveru:

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

Pokretanje bez neuspeha navodi provere pod tri naslova: Klaster, Mreža te Vreme i ključevi. Upozorenja nikada ne blokiraju. Upozorenje o grafici smo namerno zadržali: na ovom povezanom pilot klasteru, asistent u Harrow koristio je hostovani model sa sopstvenim ključem luke.

Pre instalacije
Pre instalacije
Provera pre instalacije u terminalu operatera, sa brojevima pored nje. Obratite pažnju da je ispod svakog upozorenja ispisana ispravka i da pokretanje jasno navodi da ništa nije promenilo na klasteru.

Izlazni kodovi

Kod Značenje
0 Instalacija može da se nastavi. Upozorenja ne blokiraju
1 Instalacija je blokirana: najmanje jedna provera nije prošla
2 Provera pre instalacije nije mogla da se pokrene: nije bilo moguće pročitati kubeconfig, kontekst, fajl sa vrednostima ili interfejs za programiranje aplikacija (API) klastera, ili je opcija bila pogrešna

Skripte treba da čitaju izlazni kod, a ne reči. Naša pokreće proveru pre instalacije kao prvi korak svake nadogradnje i zaustavlja se na bilo čemu osim 0.

Pokrenite nexusctl izdanja na koje prelazite, a ne onog sa kojim ste instalirali. Zahtevi potiču iz chart-a koji nosi, tako da novije izdanje može podići minimalnu verziju Kubernetes ili zahtevati više memorije, a to zna samo njegov sopstveni nexusctl. --release menja verziju koju izveštaj navodi; ne menja pravila kog chart-a se primenjuju. U Harrow čuvamo nexusctl svakog izdanja pored njegovog chart-a u zapisu o promeni, tako da se vraćanje na prethodno izdanje proverava alatom koji mu odgovara.

Svaka provera

Postoji jedanaest provera. Deset od njih daje po jedan red; provera adrese daje jedan red po hostu, tako da potpuno pokretanje ima trinaest redova. Devet provera mora da prođe, a promašaj je neuspeh. Dve, grafički čvorovi i sertifikat, trebalo bi da prođu, a promašaj je upozorenje. Poslednja kolona je tekst zahteva koji svaki red prenosi u izveštaj; CPU u njemu označava centralnu procesorsku jedinicu.

ID provere Odeljak Mora da prođe Zahtev koji ispisuje
kubernetes-version cluster da Kubernetes 1.33 ili noviji
nodes-ready cluster da Svaki čvor spreman
storage-class cluster da Klasa skladišta za podatke
resources cluster da Dovoljno CPU i memorije za izdanje
graphics-nodes cluster ne Grafički čvorovi
ingress-class network da Ingress klasa za tri adrese
ingress-ports network da Ingress kontroler otvoren na portovima 80 i 443
address-console, address-api, address-auth network da Adresa console, api ili auth se razrešava u DNS
certificate network ne Sertifikat važi još 30 dana
custodians time-and-keys da Osobe koje drže ključeve za oporavak ove instalacije
installation-name time-and-keys da Sopstveni trajni naziv ove instalacije

kubernetes-version

Čita verziju API servera i upoređuje je sa minimalnom verzijom chart-a. Pronalazi, na primer, 1.33.6+k3s1. Ispod 1.33 ne prolazi, uz ispravku upgrade the cluster to 1.33 or later. Ako niz verzije nije onaj koji nexusctl može da pročita, provera ne prolazi umesto da nagađa.

nodes-ready

Navodi čvorove i broji one čiji je uslov Ready tačan, kao 3 of 3. Svaki čvor koji nije spreman se imenuje, a ispravka vam govori da ga vratite u stanje Ready i pročitate njegove uslove. Klaster bez ijednog čvora ne prolazi, uz napomenu da kontekst možda ukazuje na pogrešan klaster.

storage-class

Ako vaše vrednosti postavljaju storage.className, provera traži tu klasu i ne prolazi sa <name> does not exist kada ona nedostaje. Ako ne postavljaju, traži klasu označenu kao podrazumevanu i prijavljuje je kao local-path (default). Bez podrazumevane klase ne prolazi sa none marked default, a kolona potreba objašnjava zašto je to važno: the database cannot claim a disk. Ako su dve klase označene kao podrazumevane, klaster novom zahtevu dodeljuje najnoviju, pa se ona i prijavljuje.

resources

Izračunava šta izdanje zahteva na osnovu chart-a i vaših vrednosti, a zatim sabira raspoloživa jezgra centralne procesorske jedinice (CPU) i memoriju svakog čvora koji je Ready, nije cordoned i nema taint NoSchedule ili NoExecute. Podovi chart-a nemaju tolerations, tako da čvor sa taint-om ne može da ih pokreće i ne računa se. Klaster sa nedovoljno resursa ne prolazi uz tačan manjak, na primer add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Potrebe se zaokružuju naviše, a raspoloživi resursi naniže, tako da vam provera nikada ne prikazuje povoljniju sliku.

graphics-nodes

Traži Ready čvor sa grafičkom procesorskom jedinicom (GPU) koju može da dodeli, nvidia.com/gpu. Ako je nema, upozorava: the assistant will need a hosted model. Provera pre instalacije ovo tretira kao savet i nikada ne blokira zbog toga, jer asistent umesto toga može da odgovara putem hostovanog modela veštačke inteligencije (AI). Poglavlje 2.14, AI provajderi i modeli, obuhvata oba načina.

ingress-class

Ako je ingress.className postavljen, provera traži tu klasu. Ako nije, traži tačno jednu klasu označenu kao podrazumevanu. Dve klase označene kao podrazumevane takođe dovode do neuspeha, jer API server tada odbija Ingress bez klase. Provera se preskače, a njen red izostavlja, kada je ingress.enabled false.

ingress-ports

U namespace-u navedenom u networkPolicy.ingressNamespace (podrazumevano kube-system, gde k3s pokreće Traefik) traži jedan LoadBalancer ili NodePort Service koji izlaže i 80 i 443. Mrežna politika chart-a dozvoljava samo tom namespace-u da pristupi trima javnim Services, tako da ingress kontroler bilo gde drugde ne bi mogao da opslužuje Nexus čak i kada bi osluškivao. Ispravka navodi oba rešenja: izložite kontroler tamo ili postavite networkPolicy.ingressNamespace na mesto gde radi. Preskače se kada je ingress.enabled false.

address

Razrešava hosts.console, hosts.api i hosts.auth sa vaše radne stanice, po pet sekundi za svaki, i ispisuje jedan red po hostu. Host bez zapisa ne prolazi sa <host> → no record. Nepostavljen host ne prolazi sa hosts.<key> is not set. Kada ime ima više adresa, red prikazuje prvu, IPv4 pre IPv6, i koliko ih još ima.

certificate

Pokreće se samo kada je tls.mode existing i tls.existingSecret navodi Secret; sa cert-manager ili none ne postoji vaš sertifikat koji bi se čitao, pa se red izostavlja. Čita tls.crt iz Secret-a u namespace-u instalacije i ništa drugo. Sertifikat koji važi 30 dana ili duže prolazi kao ends 3 Nov 2027. Za onaj koji ističe ranije prikazuje se upozorenje ends in 9 days; za onaj koji je već istekao upozorenje ended 4 days ago. Secret koji nedostaje, ili onaj bez sertifikata, daje upozorenje sa ispravkom.

custodians

Čita keys.custody.recipients. Ako ih nema, ne prolazi sa kodom KEYS_CUSTODIAN_MISSING. Ako je bilo koji primalac primer čuvara ključeva iz sopstvenih fajlova sa vrednostima chart-a, ne prolazi sa KEYS_CUSTODIAN_EXAMPLE, jer niko ne drži taj ključ i ključevi za oporavak instalacije bili bi zapečaćeni ni za koga. Uspešna provera ispisuje broj, na primer 3 custodians.

installation-name

Čita keys.installationName. Ako nije postavljen, ne prolazi sa INSTALLATION_NAME_MISSING. Ako je postavljen na primer naziva iz fajlova sa vrednostima chart-a, ne prolazi sa INSTALLATION_NAME_EXAMPLE. Uspešna provera ispisuje naziv. Kolona potreba objašnjava zašto je ova provera važnija od većine: the first key-store bootstrap mints the installation identity under it, permanently.

Poslednje dve provere prijavljuju tačno one kodove sa kojima sam chart odbija instalaciju. Provera pre instalacije vam to samo kaže ranije, pre nego što je Helm bilo šta napravio.

Datoteke izveštaja

Svako pokretanje čuva dva fajla u --report-dir, nazvana prema vremenu pokretanja: preflight-2026-11-12-0902.txt, redove onako kako su ispisani, bez kodova boja, i preflight-2026-11-12-0902.json, isto pokretanje u fiksnom formatu koji program može da pročita. Izlaz u terminalu i sačuvani redovi potiču iz iste liste, tako da se nikada ne razlikuju.

JSON izveštaj prati šemu nexus.preflight/v1:

Polje Šta sadrži
schema Tačno nexus.preflight/v1
tool Objekat: name (nexusctl) i version
release Provereno izdanje
ran_at Kada je pokrenuto, u koordinisanom univerzalnom vremenu (UTC)
context Naziv kube konteksta
values Samo osnovni naziv fajla sa vrednostima
read_only Uvek true
checks Jedan unos po redu: id, section, name, requirement, must_pass, outcome (pass, warn ili fail), found, needs, fix, a kod promašaja sa mašinskim uzrokom i code
counts passed, warnings i failed
can_install true kada ništa nije bilo neuspešno
report_file Naziv fajla .txt
transcript Objekat: title (nexusctl preflight) i lines, svaki red sa svojim kind (prompt, ok, warn, bad, note, out ili blank), svojim text i at, a ponekad i marks

Izveštaj je napravljen tako da se prikazuje pre nego što se bilo ko prijavi, pa ne sadrži korisničko ime, naziv hosta radne stanice, putanju fajla, token niti išta iz vašeg kubeconfig-a. values je osnovni naziv, a context je naziv konteksta. Ako bi izveštaj nekog pokretanja prekršio bilo koje od ovih pravila, nexusctl odbija da ga ispiše, sačuva ili preda, i to navodi. Izveštaj ima najviše 256 KiB, najviše 64 provere i 512 znakova u bilo kom pojedinačnom tekstualnom polju.

Kako izveštaj stiže do konzole

Jedini upis provere pre instalacije je gotov izveštaj, predat servisu za ključeve instalacije, nexus-keys, kako bi ga instaler konzole mogao prikazati na svojoj stranici provere pre instalacije pre nego što je iko preuzeo instalaciju. --record određuje da li će se pokušati:

--record Šta se dešava
auto Predaje izveštaj samo kada namespace ima Deployment nexus-keys
always Insistira; provera pre instalacije izlazi sa 2 ako nema čemu da ga preda
never Ne predaje ga

Dakle, pokretanje pre prve instalacije nema čemu da preda izveštaj i zadržava ga na vašoj radnoj stanici. Pokretanje nakon instalacije, a pre preuzimanja, ga beleži.

Predaja koristi vaš sopstveni pristup klasteru. nexusctl pokreće /app/nexus-keys preflight-record u kontejneru keys spremnog poda nexus-keys i prosleđuje izveštaj putem standardnog ulaza. Isto je kao:

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

Servis za ključeve proverava izveštaj prema istim pravilima koja primenjuje nexusctl i čuva samo najnoviji. Kada je izveštaj predat, nexusctl ispisuje još jedan red koji to navodi, a sačuvani JSON dobija note koji beleži predaju.

Instaler konzole ga čita sa javne rute servisa za ključeve GET /v1/installation/preflight. Ta ruta odgovara samo dok instalacija nije preuzeta: pre nego što je bilo koji izveštaj zabeležen odgovara sa 404 RECORD_NOT_FOUND, a kada neko preuzme instalaciju trajno odgovara sa ROUTE_NOT_FOUND, tačno kao i ruta za preuzimanje. Izveštaj predat nakon preuzimanja odbija se sa INSTALLATION_CLAIMED.

Na konzoli se pokretanje sa neuspesima prikazuje kao „Provera pre instalacije ne može da se nastavi“: broj neuspešnih, upozorenja i uspešnih, zatim svaka provera grupisana pod „Mora da prođe“ i „Trebalo bi da prođe“, pri čemu su prve one koje nisu prošle, a pored svake su reči o pronađenom. Pokretanje bez neuspeha ne dobija tu stranicu; konzola prelazi direktno na preuzimanje (poglavlje 2.12, Prvo pokretanje).

Provera pre instalacije ne može da se nastavi
Preflight provera ne može da se nastavi
Stranica konzole za pokretanje provere pre instalacije koje ne može da se nastavi. Neuspešne provere su prve, svaka opisana rečima uz ono što je pronađeno, a instalacija ostaje blokirana dok ne prođu.
Tri kolone. Levo, „Radna stanica operatera“: okvir „nexusctl preflight --context --values“ sa dva izlaza ispod, „preflight-<time>.txt“ i „preflight-<time>.json“. U sredini, „Instalacija, nepreuzeta“: okvir „nexus-keys“ sa oznakom „preflight-record, samo najnoviji izveštaj“. Strelica od levog okvira do nexus-keys označena je sa „pod exec sa Vašim sopstvenim pristupom klasteru (--record auto ili always)“. Desno, „Pregledač, pre prijave“: okvir „Instalater konzole, preflight provera ne može da se nastavi“. Strelica od nexus-keys do njega označena je sa „GET /v1/installation/preflight“. Ispod srednjeg okvira, mala napomena glasi „nakon preuzimanja: ROUTE_NOT_FOUND“.
Kuda odlazi jedan izveštaj preflight provere, od radne stanice operatera do pregledača.

Pristup koji je potreban za izvršavanje

Preflight provera se pokreće kao Vi, sa Vašim kubeconfig fajlom. Nalog mora da ima pravo čitanja:

  • čvorova, za provere verzije, spremnosti, resursa i grafike;
  • klasa skladišta i klasa ingress-a;
  • servisa u ingress namespace-u;
  • TLS Secret objekta u namespace-u instalacije, kada se pokreće provera sertifikata.

Kada je čitanje odbijeno, red prikazuje could not read <what> (the cluster refused), a ispravka navodi koje pravo čitanja treba dodeliti. Tekst nikada ne sadrži adresu servera niti njegov sopstveni tekst greške, jer izveštaj može biti prikazan pre prijave. Za predaju je potrebno i pods/exec na nexus-keys podovima; bez toga, auto čuva fajlove i ispisuje upozorenje, a always završava sa 2.

Kada sama predinstalaciona provera ne može da se pokrene

Izlazni kod 2 znači da izveštaj nije napravljen. Poruka na standardnom izlazu za greške navodi razlog:

Poruka Šta učiniti
--context is required: the kube context to check Dodajte --context
--values is required: the values file the install will use Dodajte --values
could not read the values file harrow-values.yaml Proverite putanju i dozvole fajla
preflight takes flags only Uklonite suvišan argument
the report breaks its contract and was not printed, saved or handed over Polje bi sadržalo nešto privatno; prijavite to kompaniji Adverant uz oznake (flags) korišćene pri pokretanju
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to Najpre izvršite instalaciju ili koristite --record auto
could not hand the report to this installation Proverite da li imate pristup za exec u nexus-keys

Klaster čijem API-ju nije moguće pristupiti takođe završava sa 2. Ispravite kubeconfig ili mrežu i pokrenite ponovo.

Kada se preflight provera završi sa 0 failed, pređite na poglavlje 2.6, Instaliranje izdanja Community na Kubernetes, da biste instalirali Community, ili na poglavlje 2.7, Instaliranje izdanja Enterprise i primena licence, za Enterprise.