Verzia 1.0.0-alpha.1najnovšia
Kapitola 2.9
Obraz inštalačného disku
Spustite fyzický server alebo virtuálny stroj z inštalačného obrazu Nexus a systém nainštaluje operačný systém, k3s, cert-manager a Nexus bez pripojenia k sieti, pričom pred použitím skontroluje každý súbor.
Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

Kancelária prístavného kapitána na východnom nábreží v Harrow má jeden server, žiadny internet a nikoho na mieste, kto by prevádzkoval Kubernetes. Tomás Reilly na ňom napriek tomu potreboval Nexus. Zapísal obraz na kľúč USB (Universal Serial Bus), vedľa neho vložil druhý, malý kľúč so štyrmi riadkami nastavení a spustil server. O hodinu neskôr sa na obrazovke zobrazila adresa konzoly a tri riadky, ktoré bolo potrebné pridať do súboru hosts. Nezadával jediný príkaz Kubernetes.
To je úlohou inštalačného obrazu disku. Zapíše minimálny operačný systém na disk servera, potom pri prvom spustení skontroluje každý súbor, ktorý obsahuje, voči kľúču vydania Adverant, nainštaluje k3s bez siete, naimportuje každý obraz, nainštaluje cert-manager a Nexus a skontroluje, či každý pod beží. Každý krok sa zastaví s uvedením konkrétneho dôvodu v okamihu, keď niečo nie je v poriadku. Nikde neexistuje žiadny obmedzený režim ani predvolené heslo.
Dva obrazy
Každé vydanie prichádza vo forme dvoch druhov obrazov pre dve architektúry procesorov, amd64 a arm64.
| Súbor | Čo obsahuje | Kto si ho môže stiahnuť |
|---|---|---|
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso |
Iba inštalátor: operačný systém, k3s v1.33.6+k3s1, cert-manager v1.21.3 a inštalátor pre prvé spustenie. Funguje pre obe edície a neobsahuje žiadne obrazy systému Nexus. | Ktokoľvek, z downloads.adverant.ai |
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso |
Ten istý inštalátor s pridaným offline balíkom danej edície ako druhým oddielom s označením NEXUS-BUNDLE. Jedno médium nainštaluje všetko. |
Community: ktokoľvek. Enterprise: iba z vášho účtu Adverant |
<arch> je amd64 alebo arm64 a <edition> je community alebo enterprise.
Inštalátor vždy hľadá iba súborový systém s označením NEXUS-BUNDLE. V obraze „všetko v jednom“ (all-in-one) je to oddiel na samotnom obraze. Pri obraze obsahujúcom iba inštalátor prinesiete balík na druhom disku alebo kľúči s týmto označením, čo je praktické, keď inštalujete viacero lokalít z jedného inštalačného kľúča a meníte iba balík. Balík popisuje kapitola 2.10, Inštalácia v izolovanej sieti (air-gapped).
Obrazy Enterprise a balíky Enterprise nie sú nikdy anonymné. Sťahujete si ich zo svojho účtu Adverant na adrese https://account.adverant.ai, na stránke Stiahnuté súbory (Downloads), vedľa vašej licencie. Obrazy a balíky Community sú verejné.
Z čoho je obraz zostavený
Operačný systém je založený na systéme Debian 13 a nejde o oficiálny obraz systému Debian. Obsahuje základný systém Debian a nič iné: žiadne extra balíky, žiadne pracovné prostredie a žiadne zrkadlo (mirror). k3s si prináša vlastné behové prostredie pre kontajnery a sieťovanie. Reťazec spúšťania (shim, GRUB, jadro a počiatočný ramdisk) sa bajt po bajte zhoduje s tým, ktorý dodáva Debian, takže stroj so zapnutou funkciou Secure Boot ho spustí ako akýkoľvek inštalátor systému Debian.
Dve zostavenia toho istého vydania poskytujú identické obrazy, bajt po bajte, a vydanie nie je zverejnené, kým to tak nie je. Zdrojové balíky systému Debian pre každý binárny súbor na obraze sú zverejnené vedľa neho ako nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, v tom istom zozname kontrolných súčtov.
Kontrola stiahnutého súboru pred zápisom
Adresár obrazov na downloads.adverant.ai obsahuje obrazy, súbor SHA256SUMS pokrývajúci každý zverejnený súbor a SHA256SUMS.sigstore.json, podpis tohto zoznamu vytvorený kľúčom vydania Adverant. Verejný kľúč vydania získajte samostatne, uložte ho ako release.pub a skontrolujte jeho odtlačok (fingerprint), ako popisuje kapitola 2.4, Získanie a overenie vydania.
- Overte podpis na zozname kontrolných súčtov. Pre vydania systému Nexus neexistuje žiadny záznam transparentnosti (transparency log), preto sa vyžaduje príznak, ktorý preskočí vyhľadávanie v zázname.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
--bundle SHA256SUMS.sigstore.json SHA256SUMSVerified OK
- Skontrolujte stiahnutý obraz voči zoznamu:
grep nexus-alpha-community-1.0.0-alpha.1-amd64.iso SHA256SUMS | sha256sum -c -nexus-alpha-community-1.0.0-alpha.1-amd64.iso: OK
Na počítači Mac použite shasum -a 256 -c - namiesto sha256sum -c -.
- Zapíšte obraz na kľúč USB pomocou nástroja, ktorý bežne používate, alebo ho pripojte k virtuálnemu stroju ako optický disk.
k3s zverejňuje kontrolné súčty pre svoje súbory vydania a žiadny podpis, takže súbory k3s vo vnútri obrazu sa kontrolujú voči kontrolným súčtom, ktoré zverejňuje k3s, z rovnakého zdroja ako súbory. Všetko, čo zostavil Adverant, je podpísané.
Balíky po častiach
Balík, ktorý prenášate na samostatnom kľúči, má niekoľko gigabajtov. Niektoré súborové systémy, medzi nimi aj FAT (File Allocation Table), nedokážu uchovať súbor s veľkosťou 4 GiB alebo viac, preto sú súbory balíka zverejňované po častiach s veľkosťou 2047 MiB, ktoré sa zmestia na akýkoľvek kľúč. Pred použitím spojte časti v správnom poradí späť dohromady a skontrolujte spojený súbor voči jeho .sha256.
Potrebný hardvér
Prvé spustenie skontroluje stroj predtým, než sa čohokoľvek dotkne, a odmietne pokračovať, ak je stroj príliš malý.
| Kontrola | Základňa | Kedy sa kontroluje |
|---|---|---|
| Architektúra | Vlastná architektúra obrazu: obraz amd64 na amd64, arm64 na arm64 | Prvé spustenie |
| Pamäť | 16 GiB | Prvé spustenie |
| Cieľový disk | Presne jeden prázdny disk s veľkosťou aspoň 64 GB alebo disk, ktorý určuje konfiguračný zväzok (seed) | Pred zápisom operačného systému |
Voľné miesto na / |
50 GB po nainštalovaní operačného systému | Prvé spustenie |
| Hodiny | Nie staršie ako dátum zostavenia obrazu | Prvé spustenie |
Toto sú minimálne hodnoty, nie odporúčanie. Pri predvolených nastaveniach chartu predstavujú samotné zväzky systému Nexus spolu 142 GiB, takže 64 GB disk síce prejde inštalátorom, ale zaplní sa v priebehu niekoľkých dní. Použite to, čo by mal mať jeden uzol: 8 vCPU (virtual central processing units), 32 GiB pamäte a 250 GB SSD (solid-state drive). Na testovacie účely (evaluation) postačujú štyri vCPU, 16 GiB a 200 GB.
Kontrola hodín je tam preto, lebo server nemá pri inštalácii žiadnu sieť, a teda ani žiadnu časovú službu. Certifikáty a podpisy sa kontrolujú voči hodinám. Ak sú hardvérové hodiny stroja pozadu oproti dátumu zostavenia obrazu, prvé spustenie sa zastaví a požiada vás o ich nastavenie. Nastavte ich v nastaveniach firmvéru a spustite stroj znova.
Fyzické servery (bare metal) a virtuálne stroje
Obraz sa spúšťa na firmvéri UEFI (Unified Extensible Firmware Interface), rovnako na fyzických serveroch aj na virtuálnych strojoch. Zavádzač (boot loader) nainštaluje na cestu pre vymeniteľné médiá aj na zvyčajnú cestu, takže VM (virtual machine) bez uložených spúšťacích záznamov ho po prvom reštarte napriek tomu nájde. Priraďte virtuálnemu stroju pamäť a disk podľa tabuľky vyššie, jeden prázdny virtuálny disk a obraz ako disk CD.
Inštalátor vyberá cieľový disk podľa prísneho pravidla a nikdy nevyberie „prvý disk“.
- Preskočí médium, z ktorého sa spustil.
- Preskočí vymeniteľné disky, pokiaľ niektorý z nich neurčuje konfiguračný zväzok (seed).
- Preskočí akýkoľvek disk, ktorý už má tabuľku oddielov akéhokoľvek druhu.
- Preskočí disky menšie ako 64 GB a oznámi to na konzole.
- Inštaluje iba vtedy, keď zostane presne jeden disk.
Na serveri s dvoma prázdnymi diskami sa zastaví a požiada vás o výber. Vyberiete tak, že pomenujete disk v konfiguračnom zväzku (seed) pomocou wipe: true, čo je jediný spôsob, akým kedy zapíše na disk, ktorý už obsahuje oddiely.
Zväzok NEXUS-SEED
Konfiguračný zväzok (seed) je malý zväzok, zvyčajne kľúč USB, so súborovým systémom označeným ako NEXUS-SEED a súborom seed.yaml na najvyššej úrovni. Inštalátor ho pripojí iba na čítanie, prečíta nastavenia a znova ho pripojí na zápis až na úplnom konci, aby vám tam zanechal heslo operačného systému.
# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m| Kľúč | Čo nastavuje | Keď chýba |
|---|---|---|
domain |
Doména inštalácie. Inštalátor z nej odvodí tri hostiteľské názvy: console.<domain>, api.<domain> a auth.<domain>. |
Vyžiadané na konzole servera |
adminEmail |
E-mail osoby, ktorá bude prvým správcom | Vyžiadané na konzole servera |
edition |
community alebo enterprise. Ak je nastavené, musí sa zhodovať s edíciou balíka. |
Prevzaté z balíka |
timeout |
Ako dlho môže trvať inštalácia cert-manager a Nexus, ako trvanie, napríklad 30m alebo 1h |
30m |
time |
Aktuálny čas v UTC, vo formáte, ktorý vypisuje správa hodín (2026-11-14T09:00:00Z), pre stroj, ktorého hardvérové hodiny sa nedajú nastaviť alebo si nastavenie neudržia. Offline stroj nemá žiadny časový server, ktorého by sa mohol opýtať. |
Použijú sa hardvérové hodiny |
disk |
Cieľový disk, ako /dev/<name>, používa sa iba spolu s wipe: true |
Pravidlo prázdneho disku uvedené vyššie |
wipe |
true umožní inštalátoru vymazať disk, ktorý určuje disk |
Žiadny disk sa nikdy nevymaže |
Pre edíciu Enterprise vložte licenčný súbor na ten istý zväzok ako licence.json. Bez neho sa prvé spustenie zastaví v kroku spracovania konfiguračného zväzku (seed) a oznámi, že licencia chýba. Edícia Community nepotrebuje žiadnu licenciu a pre Community je celý konfiguračný zväzok voliteľný: inštalátor si vyžiada doménu a e-mail na konzole a pokračuje ďalej.
Inštalátor číta každý riadok ako key: value na začiatku riadka. Píšte jeden kľúč na riadok, na najvyššej úrovni, bez úvodzoviek a bez odsadenia. Hodnota v úvodzovkách sa prečíta aj s úvodzovkami.
Pri prvom spustení si inštalátor na konzole vyžiada aj správcu úložiska kľúčov (custodian): verejnú polovicu kľúča age, age1..., vytvorenú na vlastnom stroji správcu kľúčov pomocou age-keygen -o custodian.key. Úložisko kľúčov k nej zapečatí svoje obnovovacie kľúče. Správcov kľúčov vysvetľuje kapitola 2.8, Inštalácie na jeden stroj. Správca kľúčov uchováva súkromnú polovicu offline a v bezpečí: bez nej nemôže nikto po reštarte odpečatiť úložisko kľúčov.
Čo sa deje od zapnutia po zobrazenie adresy konzoly
Prvá fáza: operačný systém
Obraz sa spustí do bezobslužného inštalátora systému Debian. Nekonfiguruje sieť, nepoužíva zrkadlo (mirror) ani neinštaluje žiadny balík okrem základného systému. Nastaví časové pásmo na UTC (Coordinated Universal Time), zakáže prihlásenie používateľa root a vytvorí jedného používateľa, nexus, ktorého heslo je uzamknuté. Vyberie cieľový disk podľa pravidla uvedeného vyššie a zapíše disk GPT (globally unique identifier partition table) so systémovým oddielom EFI (Extensible Firmware Interface) a jedným koreňovým súborovým systémom ext4, bez odkladacieho priestoru (swap).
Na konci skopíruje inštalátor systému Nexus do nového systému, skontroluje každý skopírovaný súbor voči zoznamu kontrolných súčtov obrazu a povolí službu prvého spustenia. Ak sa niektorý skopírovaný súbor nezhoduje, na tomto mieste sa zastaví. Potom vysunie médium a reštartuje sa.
Druhá fáza: prvé spustenie
Pri prvom spustení sa raz spustí služba nexus-install. Každý krok sa vypisuje na konzolu servera a do žurnálu a zaznamená sa ako dokončený, takže opakovaný pokus začína od prvého kroku, ktorý ešte nie je dokončený. Služba ako celok môže bežať až štyri hodiny, kým ju systemd zastaví, čo ponecháva priestor pre pomalý disk a hodinové čakanie na kľúč s balíkom.
- Predbežná kontrola (Preflight). Architektúra, hodiny, pamäť a voľné miesto na disku, ako je uvedené v tabuľke vyššie.
- Obsah (Payload). Vlastné súbory inštalátora: podpis na jeho zozname kontrolných súčtov pomocou kľúča vydania, ktorý obsahuje, a potom každý súbor voči tomuto zoznamu.
- Konfiguračný zväzok (Seed). Prečíta
seed.yamla na konzole si vyžiada všetko, čo chýba. - Balík (Bundle). Nájde zväzok označený ako
NEXUS-BUNDLEa pripojí ho iba na čítanie. Ak tam žiadny nie je, vypíšewaiting-for-bundlea počká až hodinu, kým ho pripojíte. Potom pred akýmkoľvek importom spustí úplnú kontrolu balíka, ktorá končí správouVERIFY-BUNDLE PASS, pomocou kľúča vydania, ktorý obsahuje. Balík Enterprise vyžadujelicence.jsonna konfiguračnom zväzku (seed) a edícia konfiguračného zväzku sa musí zhodovať s edíciou balíka. - k3s. Nainštaluje k3s v1.33.6+k3s1 z vlastných súborov obrazu s vypnutým sťahovaním a počká až desať minút, kým uzol prejde do stavu Ready. Potom odstráni archív obrazov k3s pre izolovanú sieť (air-gap), aby sa obrazy neimportovali znova pri každom spustení.
- Import. Naimportuje každý overený obraz z balíka a obrazy nástroja cert-manager do úložiska kontajnerov uzla. Z registra sa nikdy nič nesťahuje.
- cert-manager, potom Nexus. Nainštaluje cert-manager v1.21.3, potom chart systému Nexus z balíka, oboje v rámci časového limitu
timeoutz konfiguračného zväzku. - Akceptácia (Acceptance). Skontroluje, či je každý pod v stave Running a či bola každá úloha (Job) typu hook dokončená.
- Prihlasovacie údaje (Credential). Pridelí používateľovi operačného systému
nexusnové náhodné heslo, raz ho zobrazí na konzole a zapíše ho donexus-os-password.txtna konfiguračnom zväzku (seed), ak je možné na tento zväzok zapisovať.
Kontrola balíka v kroku 4 je ten istý skript, ktorý spúšťate ručne v kapitole 2.10, Inštalácia v izolovanej sieti (air-gapped), a vypisuje tie isté riadky:
1 SHA256SUMS OK files=<n>
2 SHA256SUMS signature OK
3 images signed + SBOM-attested: <n>
4 helm lint --strict OK nexus-1.0.0-alpha.1.tgz
5 coverage OK rendered=<n> lock=<n>
6 source offer OK images=5 files=<n>
VERIFY-BUNDLE PASS files=<n> images=<n>
Riadok 3 počíta obrazy, ktoré majú platný podpis a podpísaný SBOM (software bill of materials), čo je zoznam toho, čo každý obraz obsahuje. Počty (<n>) závisia od edície. Dôležitý je posledný riadok.
Inštalácia zapíše hodnoty v aktuálnej forme chartu: global.domain a tri názvy hosts.* z domény konfiguračného zväzku (seed) a keys.custody.recipients zo správcu kľúčov (custodian), ktorého ste zadali na konzole. Inštaluje z vlastného chartu a obrazov balíka, takže vydanie na disku je presne to vydanie, ktoré bolo skontrolované.
Posledné riadky na konzole
Keď prejde každý krok, konzola raz zobrazí heslo operačného systému a adresu, ktorú treba otvoriť:
nexus-install: OS login: user nexus, password <shown-once> (shown once; change it with passwd)
nexus-install: DONE: https://console.harrow.example (add to /etc/hosts: 10.20.4.15 console.harrow.example api.harrow.example auth.harrow.example)
Zapíšte si heslo alebo si ho vezmite z kľúča s konfiguračným zväzkom (seed), potom sa prihláste ako nexus a zmeňte ho pomocou passwd. Nikto, vrátane spoločnosti Adverant, nepozná predvolené heslo pre tento stroj, pretože žiadne neexistuje.
Adresa v riadku hosts je vlastná adresa servera. Keďže na nábreží nebolo žiadne DNS (Domain Name System), Tomás pridal tento jeden riadok do súboru hosts každého notebooku, ktorý mal používať konzolu. V lokalite s DNS namiesto toho pridajte záznamy pre tieto tri názvy.
Po inštalácii
Inštalácia je neprevzatá. Nikto sa nemôže prihlásiť, kým ju niekto neprevezme v prehliadači porovnaním odtlačku (fingerprint) inštalácie s tým, ktorý zobrazuje server. Prevzatie, prvého správcu a prístupový kľúč (passkey) popisuje kapitola 2.12, Prvé spustenie. Prvým správcom by mala byť osoba, ktorej e-mail je uvedený v konfiguračnom zväzku (seed).
Vlastný súbor kubeconfig uzla sa nachádza v /etc/rancher/k3s/k3s.yaml a je čitateľný iba pre používateľa root. Ak chcete pracovať s klastrom z pracovnej stanice, vypíše ho príkaz nexusctl kubeconfig, ako popisuje kapitola 2.8, Inštalácie na jeden stroj.
Aktualizácie prichádzajú rovnakým spôsobom ako inštalácia: vydanie na podpísanom médiu, skontrolované voči kľúču, ktorý je už nainštalovaný na serveri, a nikdy nie voči kľúču, ktorý si disk prináša so sebou. Túto kontrolu popisuje kapitola 2.10, Inštalácia v izolovanej sieti (air-gapped).
Ak tento postup zlyhá
Každé zlyhanie vypíše na konzolu nexus-install: FAILED <step>: <what is missing> a to isté zapíše do /var/lib/nexus/install.state. Odstráňte príčinu a spustite inštaláciu znova od prvého kroku, ktorý nie je dokončený:
sudo nexus-install retry| Správa | Čo to znamená | Čo robiť |
|---|---|---|
FAILED preflight: payload is for arm64, this machine is amd64 |
Spustili ste obraz inej architektúry. | Použite obraz pre architektúru tohto stroja. |
FAILED preflight: memory 11 GiB, need >= 16 GiB |
Stroj má menej pamäte, než je minimálna hodnota. | Pridajte pamäť alebo priraďte viac pamäte virtuálnemu stroju (VM). |
FAILED preflight: free disk 38 GB on /, need >= 50 GB |
Koreňový súborový systém je príliš malý. | Inštalujte na väčší disk. |
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed |
Hardvérové hodiny sú pozadu oproti dátumu zostavenia inštalátora. | Nastavte hodiny vo firmvéri alebo zadajte time v seed.yaml a skúste to znova. |
FAILED payload: SHA256SUMS signature does not verify |
Vlastné súbory inštalátora nie sú tie, ktoré podpísal Adverant. | Zastavte. Stiahnite obraz znova a pred zápisom ho skontrolujte. |
FAILED seed: the installation domain and the first administrator e-mail are required |
Neposkytol ich ani konfiguračný zväzok (seed), ani konzola. | Pridajte ich do seed.yaml alebo odpovedzte na výzvy. |
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) |
Balík je edície Enterprise a konfiguračný zväzok (seed) nemá žiadnu licenciu. | Vložte licence.json na konfiguračný zväzok (seed). |
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h |
Včas nebol pripojený žiadny balík. | Pripojte kľúč s balíkom a skúste to znova. |
FAILED bundle: the bundle does not verify with this installer's release key |
Kontrola balíka neskončila správou VERIFY-BUNDLE PASS. Jej vlastný výstup nad správou uvádza názov kroku. |
Zastavte. Nepoužívajte tento balík. Získajte nový. |
FAILED bundle: the seed asks for enterprise, the bundle is community |
Konfiguračný zväzok (seed) a balík sa nezhodujú. | Opravte edition v konfiguračnom zväzku (seed) alebo prineste správny balík. |
FAILED k3s: node not Ready within 10 min |
k3s sa nespustil. | Skontrolujte žurnál pre k3s a potom to skúste znova. |
FAILED nexus: helm install nexus |
Chart sa nenainštaloval v rámci časového limitu. | Pozrite sa na kubectl -n nexus get pods,jobs, zvýšte timeout v konfiguračnom zväzku (seed), ak je stroj pomalý, a skúste to znova. |
FAILED acceptance: pods not ready |
Niektoré pody po inštalácii nebežia. | Správa uvádza až päť z nich. Prečítajte si ich udalosti (events), opravte chybu a skúste to znova. |
FAILED acceptance: jobs not complete: <jobs> |
Úloha (Job) typu hook sa nedokončila. | Prečítajte si záznam (log) uvedenej úlohy (Job) pomocou kubectl -n nexus logs job/<name>, opravte to, čo hlási, a skúste to znova. |
Pred zápisom operačného systému môže inštaláciu zastaviť aj výber disku. Jeho správa začína nexus select-disk: REFUSED:. Bežnou správou je found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Určite názov disku v konfiguračnom zväzku (seed) a spustite stroj znova.
Neúspešná kontrola balíka je situácia, ktorú treba brať vážne. Znamená to, že súbory na disku nie sú súbory, ktoré podpísal Adverant, alebo bol nejaký súbor pridaný. Inštalátor v tom momente ešte nič nenaimportoval, takže server je nezmenený. Disk odložte pre svoj bezpečnostný tím.

