Přihlásit seDomluvit prezentaci

Kapitola 2.5

Předletová kontrola pomocí nexusctl

Každá kontrola, kterou `nexusctl preflight` provádí, co každá z nich čte a jak selhává, zpráva, kterou vypíše a uloží, jak se tato zpráva dostane na stránku předletové kontroly v konzoli, a každý příznak.

Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

16 min čtení

Naše první předinstalační kontrola (preflight) v Harrow Port Authority neprošla čtyřmi testy, přičemž dva z nich by nás stály mnohem více než jen jedno odpoledne. Soubor hodnot jsme založili zkopírováním příkladu z chartu a kontrola preflight odmítla jak ukázkový název instalace, tak ukázkového správce klíčů (custodian). Soukromý klíč tohoto správce totiž nikdo nevlastní. Instalaci, která je jím zapečetěna, nelze po restartu uzlu nikdy odpečetit. Kontrola preflight to odhalila během několika sekund – ještě dříve, než vůbec vzniklo něco, o co bychom mohli přijít.

Příkaz nexusctl preflight načte váš cluster a soubor hodnot, vypíše zjištěné skutečnosti, uloží zprávu a v clusteru nic nemění. Spouštějte jej před každou instalací a každým upgradem. Tato kapitola popisuje všechny prováděné kontroly, formát zprávy, kam se zpráva ukládá, a příslušné příznaky.

Provoz

Kontrola preflight potřebuje dvě věci: kube kontext clusteru, do kterého budete instalovat, a soubor hodnot, který instalace použije. Nejprve napište soubor hodnot; kapitola 2.6, Instalace edice Community v prostředí Kubernetes, prochází jednotlivé klíče. Poté:

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

Cluster čte prostřednictvím knihovny client-go výhradně pomocí volání get a list. Pokud má tls.mode hodnotu existing, vytvořte před spuštěním kontroly jmenný prostor nexus a objekt Secret pro Transport Layer Security (TLS) (kapitola 2.6, Instalace edice Community v prostředí Kubernetes, krok 3), jinak kontrola certifikátu nahlásí, že objekt Secret chybí.

Příznak Co dělá Výchozí hodnota
--context <name> Kontrolovaný kube kontext. Povinné žádná
--values <file> Soubor hodnot, který instalace použije. Povinné žádná
--namespace <name> Kam se Nexus instaluje nexus
--release <version> Kontrolované vydání vlastní verze přibaleného chartu
--report-dir <dir> Kam se ukládají oba soubory zpráv aktuální složka
--record <mode> auto, always nebo never: zda se má zpráva předat službě klíčů této instalace, aby ji zobrazila stránka instalátoru auto
--kubeconfig <file> Soubor kubeconfig, který se má načíst KUBECONFIG, poté ~/.kube/config
--ca-bundle <file> Certifikáty vaší vlastní certifikační autority (CA) pro řetězec, kterému mají kontroly důvěřovat žádná
--single-node Zkontrolovat jeden stroj pro instalaci na jeden stroj (kapitola 2.8, Instalace na jeden stroj) vypnuto

Minimální verze Kubernetes pro dané vydání není v nexusctl pevně zapsána. Čte spodní hranici kubeVersion přímo z přibaleného chartu, takže se kontrola a helm install nemohou nikdy rozcházet.

Co spuštění vypíše

Zde je výpis prvního spuštění v Harrow:

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

Pokud cokoli selže, zobrazí se nejprve selhání, poté varování a nakonec úspěšné kontroly. Každý řádek ukazuje výsledek, název kontroly, co bylo zjištěno a co je vyžadováno; každý řádek, který neprošel, má pod sebou řádek fix. Poslední dva řádky obsahují souhrn a soubor se zprávou.

Opravili jsme hodnoty, přidali dva záznamy Domain Name System (DNS), vytvořili objekt Secret a spustili kontrolu znovu:

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

Spuštění bez selhání vypíše kontroly pod třemi nadpisy: Cluster, Network a Time and keys. Varování instalaci nikdy neblokují. Varování ohledně grafických karet jsme ponechali záměrně: na tomto připojeném pilotním clusteru používal asistent v Harrow hostovaný model s vlastním klíčem přístavu.

Před instalací
Před instalací
Kontrola preflight v terminálu operátora s počty vedle ní. Všimněte si, že pod každým varováním je vypsán postup opravy a že výpis jasně uvádí, že v clusteru nebylo nic změněno.

Návratové kódy

Kód Význam
0 Instalace může pokračovat. Varování ji neblokují
1 Instalace je zablokována: nejméně jedna kontrola selhala
2 Kontrolu preflight nebylo možné spustit: nepodařilo se načíst kubeconfig, kontext, soubor hodnot nebo aplikační programové rozhraní (API) clusteru, případně byl zadán chybný příznak

Skripty by měly číst návratový kód, nikoli textový výpis. Náš skript spouští kontrolu preflight jako první krok každého upgradu a zastaví se při jakékoli jiné hodnotě než 0.

Spouštějte nexusctl toho vydání, na které přecházíte, nikoli toho, se kterým jste instalovali. Požadavky vycházejí z chartu, který si nese s sebou, takže novější vydání může zvýšit minimální vyžadovanou verzi Kubernetes nebo požadovat více paměti, což ví pouze jeho vlastní nexusctl. Příznak --release mění verzi uvedenou ve zprávě; nemění však, ze kterého chartu se použijí pravidla. V Harrow uchováváme nexusctl každého vydání společně s jeho chartem v záznamu o změně, takže případný návrat k předchozí verzi (rollback) kontroluje nástroj, který jí odpovídá.

Každá kontrola

Kontrol je celkem jedenáct. Deset z nich vytváří po jednom řádku; kontrola adres vytváří jeden řádek pro každého hostitele, takže úplný běh má třináct řádků. Devět kontrol musí projít a neúspěch znamená selhání. Dvě kontroly – grafické uzly a certifikát – by projít měly a neúspěch u nich znamená varování. Poslední sloupec obsahuje text požadavku, který si každý řádek přenáší do zprávy; zkratka CPU v něm označuje centrální procesorovou jednotku.

ID kontroly Sekce Musí projít Vypisovaný požadavek
kubernetes-version cluster ano Kubernetes 1.33 nebo novější
nodes-ready cluster ano Všechny uzly připraveny
storage-class cluster ano Třída úložiště (StorageClass) pro data
resources cluster ano Dostačující CPU a paměť pro dané vydání
graphics-nodes cluster ne Grafické uzly
ingress-class network ano Třída Ingress (IngressClass) pro tři adresy
ingress-ports network ano Kontroler Ingress otevřený na portech 80 a 443
address-console, address-api, address-auth network ano Adresa console, api nebo auth je přeložitelná v DNS
certificate network ne Certifikát platný ještě alespoň 30 dní
custodians time-and-keys ano Osoby, které drží klíče pro obnovení této instalace
installation-name time-and-keys ano Vlastní trvalý název této instalace

kubernetes-version

Načte verzi serveru API a porovná ji s minimální verzí požadovanou chartem. Zjistí například 1.33.6+k3s1. Při verzi nižší než 1.33 selže s návrhem opravy upgrade the cluster to 1.33 or later. Pokud řetězec verze není ve formátu, který nexusctl dokáže přečíst, kontrola raději selže, než aby hádala.

nodes-ready

Vypíše uzly a spočítá ty, jejichž podmínka Ready má hodnotu true, například 3 of 3. Každý uzel, který není připraven, je jmenovitě uveden a návrh opravy vás vyzve, abyste jej vrátili do stavu Ready a přečetli si jeho podmínky. Cluster bez jakýchkoli uzlů selže s nápovědou, že kontext možná ukazuje na nesprávný cluster.

storage-class

Pokud vaše hodnoty nastavují storage.className, kontrola tuto třídu vyhledá a v případě, že chybí, selže s <name> does not exist. Pokud ji nenastavují, vyhledá třídu označenou jako výchozí (default) a nahlásí ji jako local-path (default). Pokud žádná výchozí třída neexistuje, selže s none marked default a sloupec požadavků vysvětlí, proč na tom záleží: the database cannot claim a disk. Jsou-li jako výchozí označeny dvě třídy, cluster novému požadavku (claim) přiřadí tu nejnovější, a proto je nahlášena právě ta.

resources

Z chartu a vašich hodnot vypočítá, co vydání vyžaduje, a poté sečte alokovatelná jádra centrální procesorové jednotky (CPU) a paměť všech uzlů, které jsou ve stavu Ready, nejsou uzavřeny pro plánování (cordoned) a nemají příznak taint NoSchedule ani NoExecute. Pody chartu nemají žádné tolerance, takže uzel s příznakem taint je nemůže spustit a nezapočítává se. Cluster s nedostatkem prostředků selže s přesným vyčíslením chybějící kapacity, například add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Požadavky se zaokrouhlují nahoru a dostupná kapacita dolů, takže kontrola stav nikdy nepřikrášluje.

graphics-nodes

Hledá uzel ve stavu Ready s grafickou procesorovou jednotkou (GPU), kterou může alokovat, nvidia.com/gpu. Pokud žádný nenajde, vypíše varování: the assistant will need a hosted model. Kontrola preflight to bere jako doporučení a instalaci kvůli tomu nikdy neblokuje, protože asistent může místo toho odpovídat prostřednictvím hostovaného modelu AI. Obě možnosti podrobně popisuje kapitola 2.14, Poskytovatelé a modely AI.

ingress-class

Pokud je nastaven klíč ingress.className, kontrola vyhledá příslušnou třídu. Pokud není, hledá právě jednu třídu označenou jako výchozí (default). Jsou-li jako výchozí označeny dvě třídy, kontrola rovněž selže, protože server API v takovém případě odmítne objekt Ingress bez uvedené třídy. Když má ingress.enabled hodnotu false, kontrola se přeskočí a její řádek se vynechá.

ingress-ports

Ve jmenném prostoru určeném klíčem networkPolicy.ingressNamespace (ve výchozím nastavení kube-system, kde k3s provozuje Traefik) hledá jednu službu (Service) typu LoadBalancer nebo NodePort, která zpřístupňuje oba porty 80 a 443. Síťová politika chartu povoluje přístup ke třem veřejným službám pouze z tohoto jmenného prostoru, takže kontroler Ingress běžící kdekoli jinde by systém Nexus nemohl obsluhovat, ani kdyby naslouchal. Návrh opravy uvádí obě řešení: zpřístupnit kontroler v daném prostoru, nebo nastavit networkPolicy.ingressNamespace na prostor, kde běží. Když má ingress.enabled hodnotu false, kontrola se přeskočí.

address

Z vaší pracovní stanice vyhledá hosts.console, hosts.api a hosts.auth (s časovým limitem pět sekund na každou adresu) a vypíše jeden řádek pro každého hostitele. Hostitel bez záznamu selže s <host> → no record. Nenastavený hostitel selže s hosts.<key> is not set. Pokud má název více adres, řádek zobrazí první z nich (IPv4 před IPv6) a uvede, kolik je dalších.

certificate

Spouští se pouze tehdy, když má tls.mode hodnotu existing a tls.existingSecret určuje název objektu Secret; při hodnotě cert-manager nebo none neexistuje žádný váš vlastní certifikát ke čtení a řádek se vynechá. Čte pouze položku tls.crt z objektu Secret v instalačním jmenném prostoru a nic jiného. Certifikát platný ještě alespoň 30 dní projde jako ends 3 Nov 2027. Certifikát, jehož platnost končí dříve, vypíše varování ends in 9 days; certifikát s již skončenou platností vypíše varování ended 4 days ago. Chybějící objekt Secret nebo Secret bez certifikátu vypíše varování s návrhem opravy.

custodians

Čte keys.custody.recipients. Pokud není uveden žádný, selže s kódem KEYS_CUSTODIAN_MISSING. Pokud je některým z příjemců ukázkový správce klíčů (custodian) ze souborů hodnot samotného chartu, selže s kódem KEYS_CUSTODIAN_EXAMPLE, protože tento klíč nikdo nevlastní a klíče pro obnovení instalace by byly zapečetěny pro nikoho. Při úspěchu vypíše počet, například 3 custodians.

installation-name

Čte keys.installationName. Není-li hodnota nastavena, selže s kódem INSTALLATION_NAME_MISSING. Je-li nastavena na ukázkový název ze souborů hodnot chartu, selže s kódem INSTALLATION_NAME_EXAMPLE. Při úspěchu vypíše název. Sloupec požadavků vysvětluje, proč na této položce záleží více než na většině ostatních: the first key-store bootstrap mints the installation identity under it, permanently.

Poslední dvě kontroly hlásí přesně ty kódy, se kterými instalaci odmítne samotný chart. Kontrola preflight vám to jen oznámí dříve, než Helm stihne cokoli vytvořit.

Soubory zprávy

Každé spuštění uloží do --report-dir dva soubory pojmenované podle času spuštění: preflight-2026-11-12-0902.txt, což jsou vypsané řádky bez kódů barev, a preflight-2026-11-12-0902.json, což je tentýž běh v pevném formátu čitelném pro programy. Výstup v terminálu i uložené řádky pocházejí ze stejného seznamu, takže se nikdy neliší.

Zpráva ve formátu JSON odpovídá schématu nexus.preflight/v1:

Pole Co obsahuje
schema Přesně nexus.preflight/v1
tool Objekt: name (nexusctl) a version
release Kontrolované vydání
ran_at Čas spuštění v koordinovaném světovém čase (UTC)
context Název kube kontextu
values Pouze základní název souboru hodnot
read_only Vždy true
checks Jedna položka na řádek: id, section, name, requirement, must_pass, outcome (pass, warn nebo fail), found, needs, fix a v případě neúspěchu se strojově čitelnou příčinou také code
counts passed, warnings a failed
can_install true, pokud nic neselhalo
report_file Název souboru .txt
transcript Objekt: title (nexusctl preflight) a lines, každý řádek se svým kind (prompt, ok, warn, bad, note, out nebo blank), svým text a at, a někdy marks

Zpráva je navržena tak, aby ji bylo možné zobrazit ještě před přihlášením, takže neobsahuje žádné uživatelské jméno, název hostitele pracovní stanice, cestu k souboru, token ani nic z vašeho souboru kubeconfig. values je základní název souboru a context je název kontextu. Pokud by zpráva z některého spuštění měla porušit kterékoli z těchto pravidel, nexusctl ji odmítne vypsat, uložit i předat a tuto skutečnost oznámí. Zpráva má velikost nejvýše 256 KiB, obsahuje nejvýše 64 kontrol a v žádném textovém poli nemá více než 512 znaků.

Jak se zpráva dostane do konzole

Jediným zápisem, který kontrola preflight provádí, je předání hotové zprávy klíčové službě instalace, nexus-keys, aby ji instalátor v konzoli mohl zobrazit na své stránce předinstalační kontroly dříve, než si instalaci někdo nárokuje (claim). O tom, zda se má o předání pokusit, rozhoduje --record:

--record Co se stane
auto Předá zprávu pouze tehdy, když ve jmenném prostoru existuje objekt Deployment nexus-keys
always Trvá na předání; pokud zprávu není čemu předat, kontrola preflight skončí s kódem 2
never Zprávu nepředává

Spuštění před první instalací tedy nemá zprávu čemu předat a ponechá ji na vaší pracovní stanici. Spuštění po instalaci a před nárokováním (claim) ji zaznamená.

Předání využívá váš vlastní přístup ke clusteru. Příkaz nexusctl spustí /app/nexus-keys preflight-record v kontejneru keys připraveného podu nexus-keys a předá zprávu na standardní vstup. Je to totéž jako:

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

Klíčová služba zkontroluje zprávu podle stejných pravidel, jaká uplatňuje nexusctl, a uchová pouze tu nejnovější. Po předání vypíše nexusctl ještě jeden řádek s potvrzením a uložený soubor JSON získá položku note, která předání zaznamenává.

Instalátor v konzoli ji čte z veřejné cesty klíčové služby GET /v1/installation/preflight. Tato cesta odpovídá pouze tehdy, dokud si instalaci nikdo nenárokoval: před zaznamenáním jakékoli zprávy odpovídá 404 RECORD_NOT_FOUND, a jakmile si instalaci někdo nárokuje, odpovídá již trvale ROUTE_NOT_FOUND, přesně jako cesta pro nárokování. Zpráva předaná po nárokování je odmítnuta s kódem INSTALLATION_CLAIMED.

V konzoli se běh se selháními zobrazí jako „Preflight cannot continue“ (Předinstalační kontrola nemůže pokračovat): nejprve počty selhání, varování a úspěšných kontrol, poté všechny kontroly seskupené pod „Must pass“ (Musí projít) a „Should pass“ (Mělo by projít), přičemž ty, které neprošly, jsou uvedeny jako první a vedle každé z nich jsou vypsány zjištěné skutečnosti. Běh bez selhání tuto stránku vůbec nezobrazí; konzole přejde rovnou k nárokování instalace (kapitola 2.12, První spuštění).

Předinstalační kontrola nemůže pokračovat
Předinstalační kontrola nemůže pokračovat
Stránka konzole pro běh předinstalační kontroly, který nemůže pokračovat. Kontroly, které selhaly, jsou uvedeny jako první, každá je slovně popsána spolu se zjištěným stavem a instalace zůstává zablokována, dokud neprojdou.
Tři sloupce. Vlevo „Pracovní stanice operátora“: pole „nexusctl preflight --context --values“ a pod ním dva výstupy, „preflight-<time>.txt“ a „preflight-<time>.json“. Uprostřed „Instalace, nenárokovaná“: pole „nexus-keys“ s popiskem „preflight-record, pouze nejnovější zpráva“. Šipka z levého pole do nexus-keys má popisek „pod exec s vaším vlastním přístupem ke clusteru (--record auto nebo always)“. Vpravo „Prohlížeč, před přihlášením“: pole „Instalátor v konzoli, Předinstalační kontrola nemůže pokračovat“. Šipka z nexus-keys do tohoto pole má popisek „GET /v1/installation/preflight“. Pod prostředním polem je malá poznámka „po nárokování: ROUTE_NOT_FOUND“.
Cesta jedné zprávy z předinstalační kontroly – z pracovní stanice operátora až do prohlížeče.

Přístup, který spuštění vyžaduje

Kontrola preflight běží pod vaším účtem s využitím vašeho souboru kubeconfig. Účet potřebuje oprávnění číst:

  • uzly (nodes) – pro kontroly verze, připravenosti, prostředků a grafických karet;
  • třídy úložiště (StorageClass) a třídy Ingress (IngressClass);
  • služby (Services) ve jmenném prostoru kontroleru Ingress;
  • objekt TLS Secret v instalačním jmenném prostoru, pokud se spouští kontrola certifikátu.

Pokud je čtení odepřeno, řádek vypíše could not read <what> (the cluster refused) a návrh opravy uvede, jaké oprávnění ke čtení je třeba udělit. Text nikdy neobsahuje adresu serveru ani jeho vlastní chybové hlášení, protože zpráva může být zobrazena před přihlášením. Předání zprávy navíc vyžaduje oprávnění pods/exec na podech nexus-keys; bez něj auto uloží soubory a vypíše varování, zatímco always skončí s kódem 2.

Když nelze spustit samotnou předběžnou kontrolu

Návratový kód 2 znamená, že nebyla vytvořena žádná zpráva. Zpráva na standardním chybovém výstupu uvádí důvod:

Zpráva Co dělat
--context is required: the kube context to check Přidejte --context
--values is required: the values file the install will use Přidejte --values
could not read the values file harrow-values.yaml Zkontrolujte cestu a oprávnění k souboru
preflight takes flags only Odstraňte přebytečný argument
the report breaks its contract and was not printed, saved or handed over Některé pole by obsahovalo soukromé údaje; nahlaste to společnosti Adverant spolu s příznaky daného spuštění
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to Nejprve proveďte instalaci, nebo použijte --record auto
could not hand the report to this installation Zkontrolujte své oprávnění spouštět příkazy (exec) v nexus-keys

Cluster, jehož API není dostupné, rovněž skončí s kódem 2. Opravte soubor kubeconfig nebo síťové připojení a spusťte kontrolu znovu.

Jakmile kontrola preflight skončí s výsledkem 0 failed, přejděte ke kapitole 2.6, Instalace edice Community v prostředí Kubernetes, chcete-li nainstalovat edici Community, nebo ke kapitole 2.7, Instalace edice Enterprise a použití licence, pro edici Enterprise.