Verze 1.0.0-alpha.1nejnovější
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ě

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.yamlCluster č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.
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.jsonKlíč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ří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.

