InloggenBriefing plannen

Hoofdstuk 2.9

De schijfimage van het installatieprogramma

Start een kale server of een virtuele machine op vanaf de Nexus-installatie-image en deze installeert het besturingssysteem, k3s, cert-manager en Nexus zonder netwerk, waarbij elk bestand wordt gecontroleerd voordat het wordt gebruikt.

Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

17 minuten leestijd

Het havenkantoor op de oostkade van Harrow heeft één server, geen internet en niemand op locatie die met Kubernetes werkt. Toch had Tomás Reilly er Nexus op nodig. Hij schreef het image naar een USB-stick (Universal Serial Bus), plaatste er een tweede, kleine stick naast met vier regels aan instellingen en startte de server op. Een uur later toonde het scherm het adres van de console en de drie regels die aan het hosts-bestand moesten worden toegevoegd. Hij heeft geen enkel Kubernetes-commando getypt.

Dat is de taak van het schijfimage van het installatieprogramma. Het schrijft een minimaal besturingssysteem naar de schijf van de server, controleert bij het eerste opstarten elk meegeleverd bestand aan de hand van de Adverant-releasesleutel, installeert k3s zonder netwerk, importeert elk image, installeert cert-manager en Nexus, en controleert of elke pod draait. Elke stap stopt met een specifieke reden op het moment dat er iets mis is. Er is geen terugvaloptie met beperkte functionaliteit en nergens een standaardwachtwoord.

De twee images

Elke release verschijnt als twee soorten images, voor twee processorarchitecturen: amd64 en arm64.

Bestand Wat het bevat Wie het kan downloaden
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso Alleen het installatieprogramma: het besturingssysteem, k3s v1.33.6+k3s1, cert-manager v1.21.3 en het installatieprogramma voor het eerste opstarten. Het werkt voor beide edities en bevat geen Nexus-images. Iedereen, via downloads.adverant.ai
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso Hetzelfde installatieprogramma waarbij de offline bundel van die editie is toegevoegd als een tweede partitie met het label NEXUS-BUNDLE. Eén medium installeert alles. Community: iedereen. Enterprise: alleen vanuit uw Adverant-account

<arch> is amd64 of arm64, en <edition> is community of enterprise.

Het installatieprogramma zoekt uitsluitend naar een bestandssysteem met het label NEXUS-BUNDLE. In het alles-in-één-image is dat de partitie op het image zelf. Bij het image met alleen het installatieprogramma levert u de bundel aan op een tweede schijf of stick met dat label, wat handig is wanneer u meerdere locaties installeert vanaf één installatiestick en alleen de bundel wisselt. Hoofdstuk 2.10, Air-gapped installatie, beschrijft de bundel.

Enterprise-images en Enterprise-bundels zijn nooit anoniem. U downloadt ze vanuit uw Adverant-account op https://account.adverant.ai, op de pagina Downloads, naast uw licentie. Community-images en -bundels zijn openbaar.

Twee schijftekeningen staan naast elkaar. De linker, "image met alleen het installatieprogramma", heeft één partitie met het label "installatieprogramma besturingssysteem, k3s, cert-manager, installatieprogramma eerste opstart" en daarnaast een aparte USB-stick met het label "NEXUS-BUNDLE: de offline bundel van de editie". De rechter, "alles-in-één-image", heeft dezelfde eerste partitie en een tweede partitie op dezelfde schijf met het label "NEXUS-BUNDLE". Onder beide staat een kleine USB-stick met het label "NEXUS-SEED: seed.yaml, en licence.json voor Enterprise", met de opmerking "optioneel voor Community". Pijlen vanaf alle drie de labels wijzen omlaag naar één vak: "eerste opstart vindt elk onderdeel op basis van zijn label".
Het image met alleen het installatieprogramma en het alles-in-één-image, en waar elk onderdeel bij het eerste opstarten wordt gevonden.

Waar het image uit is opgebouwd

Het besturingssysteem is gebaseerd op Debian 13 en is geen officieel Debian-image. Het bevat het Debian-basissysteem en verder niets: geen extra pakketten, geen desktopomgeving en geen mirror. k3s levert zijn eigen containerruntime en netwerkfunctionaliteit mee. De opstartketen (shim, GRUB, de kernel en de initiële ramdisk) is byte voor byte identiek aan wat Debian meelevert, zodat een machine met ingeschakelde Secure Boot het opstart zoals elk ander Debian-installatieprogramma.

Twee builds van dezelfde release leveren byte voor byte identieke images op, en de release wordt pas gepubliceerd als dat het geval is. De Debian-bronpakketten voor elk binair bestand op het image worden ernaast gepubliceerd als nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, in dezelfde controlegetallenlijst.

Controleer de download voordat u deze wegschrijft

De imagemap op downloads.adverant.ai bevat de images, een SHA256SUMS-bestand dat elk gepubliceerd bestand dekt, en SHA256SUMS.sigstore.json, de handtekening over die lijst die is gemaakt met de Adverant-releasesleutel. Haal de openbare releasesleutel afzonderlijk op, sla deze op als release.pub en controleer de vingerafdruk ervan zoals beschreven in hoofdstuk 2.4, Een release ophalen en verifiëren.

  1. Verifieer de handtekening op de controlegetallenlijst. Er is geen transparantielogboek voor Nexus-releases, dus de vlag die het opzoeken in het logboek overslaat is vereist.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. Controleer het gedownloade image aan de hand van de lijst:
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

Gebruik op een Mac shasum -a 256 -c - in plaats van sha256sum -c -.

  1. Schrijf het image naar een USB-stick met het hulpmiddel dat u normaal gebruikt, of koppel het als een optische schijf aan de virtuele machine.

k3s publiceert controlegetallen voor zijn releasebestanden en geen handtekening; daarom worden de k3s-bestanden in het image gecontroleerd aan de hand van de controlegetallen die k3s publiceert, afkomstig van dezelfde bron als de bestanden zelf. Alles wat Adverant heeft gebouwd, is ondertekend.

Opgesplitste bundels

Een bundel die u op een aparte stick meeneemt, is meerdere gigabytes groot. Sommige bestandssystemen, waaronder FAT (File Allocation Table), kunnen geen bestanden van 4 GiB of groter bevatten. Daarom worden bundelbestanden gepubliceerd in delen van 2047 MiB die op elke stick passen. Voeg de delen in de juiste volgorde weer samen en controleer het samengevoegde bestand aan de hand van zijn .sha256 voordat u het gebruikt.

De benodigde hardware

Bij het eerste opstarten controleert het systeem de machine voordat het iets aanraakt, en weigert het verder te gaan als de machine te klein is.

Controle De basislaag Wanneer het wordt gecontroleerd
Architectuur Die van het image zelf: een amd64-image op amd64, arm64 op arm64 Eerste opstart
Geheugen 16 GiB Eerste opstart
Doelschijf Precies één lege schijf van ten minste 64 GB, of de schijf die in de seed wordt genoemd Voordat het besturingssysteem wordt geschreven
Vrije ruimte op / 50 GB nadat het besturingssysteem is geplaatst Eerste opstart
Klok Niet ouder dan de datum waarop het image is gebouwd Eerste opstart

Dit zijn ondergrenzen, geen aanbevelingen. Met de standaardwaarden van de chart tellen alleen de volumes van Nexus al op tot 142 GiB; een schijf van 64 GB komt dus door het installatieprogramma heen, maar loopt binnen enkele dagen vol. Gebruik wat een enkele node behoort te hebben: 8 vCPU (virtual central processing units), 32 GiB geheugen en een SSD (solid-state drive) van 250 GB. Vier vCPU, 16 GiB en 200 GB is voldoende voor een evaluatie.

De klokcontrole is aanwezig omdat de server tijdens de installatie geen netwerk en dus geen tijdservice heeft. Certificaten en handtekeningen worden gecontroleerd aan de hand van de klok. Als de hardwareklok van de machine achterloopt op de bouwdatum van het image, stopt het eerste opstarten en wordt u gevraagd de klok in te stellen. Stel deze in via de firmware-instellingen en start opnieuw op.

Fysieke servers en virtuele machines

Het image start op met UEFI-firmware (Unified Extensible Firmware Interface), zowel op fysieke servers als op virtuele machines. Het installeert de bootloader zowel op het pad voor verwisselbare media als op het gebruikelijke pad, zodat een VM (virtuele machine) zonder opgeslagen opstartvermeldingen deze na de eerste herstart toch vindt. Geef een VM het geheugen en de schijfruimte uit de bovenstaande tabel, één lege virtuele schijf en het image als cd.

Het installatieprogramma kiest de doelschijf volgens een strikte regel en kiest nooit zomaar "de eerste schijf".

  • Het slaat het medium over waarvan het is opgestart.
  • Het slaat verwisselbare schijven over, tenzij de seed er een noemt.
  • Het slaat elke schijf over die al een partitietabel heeft, van welk type dan ook.
  • Het slaat schijven onder de 64 GB over en meldt dit op de console.
  • Het installeert alleen wanneer er precies één schijf overblijft.

Op een server met twee lege schijven stopt het programma en vraagt het u om te kiezen. U kiest door de schijf bij naam te noemen in de seed, met wipe: true; dat is de enige manier waarop het ooit naar een schijf zal schrijven die al partities bevat.

Het NEXUS-SEED-volume

De seed is een klein volume, meestal een USB-stick, met een bestandssysteem met het label NEXUS-SEED en een bestand seed.yaml in de hoofdmap. Het installatieprogramma koppelt dit volume aan als alleen-lezen, leest de instellingen en koppelt het pas helemaal aan het einde opnieuw aan als beschrijfbaar, om het wachtwoord van het besturingssysteem voor u achter te laten.

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
Sleutel Wat het instelt Wanneer het ontbreekt
domain Het domein van de installatie. Het installatieprogramma leidt hier de drie hosts uit af: console.<domain>, api.<domain> en auth.<domain>. Gevraagd op de console van de server
adminEmail Het e-mailadres van de persoon die de eerste beheerder wordt Gevraagd op de console van de server
edition community of enterprise. Indien ingesteld, moet dit overeenkomen met de editie van de bundel. Overgenomen uit de bundel
timeout Hoe lang de installatie van cert-manager en Nexus mag duren, als een tijdsduur zoals 30m of 1h 30m
time De huidige tijd in UTC, in de notatie die de klokmelding weergeeft (2026-11-14T09:00:00Z), voor een machine waarvan de hardwareklok niet kan worden ingesteld of haar instelling niet vasthoudt. Een offline machine heeft geen tijdserver om te raadplegen. De hardwareklok wordt gebruikt
disk De doelschijf, als /dev/<name>, alleen gebruikt in combinatie met wipe: true De regel voor een lege schijf hierboven
wipe true geeft het installatieprogramma toestemming om de schijf te wissen die in disk wordt genoemd Er wordt nooit een schijf gewist

Plaats voor Enterprise het licentiebestand op hetzelfde volume als licence.json. Zonder dit bestand stopt het eerste opstarten bij de seed-stap met de melding dat de licentie ontbreekt. Community heeft geen licentie nodig, en voor Community is de hele seed optioneel: het installatieprogramma vraagt op de console om het domein en het e-mailadres en gaat verder.

Het installatieprogramma leest elke regel als key: value aan het begin van de regel. Schrijf één sleutel per regel, op het hoogste niveau, zonder aanhalingstekens en zonder inspringing. Een waarde tussen aanhalingstekens wordt inclusief de aanhalingstekens gelezen.

Bij het eerste opstarten vraagt het installatieprogramma op de console ook om de beheerder (custodian) van de sleutelkluis: de openbare helft van een age-sleutel, age1..., aangemaakt op de eigen machine van de beheerder met age-keygen -o custodian.key. De sleutelkluis verzegelt zijn herstelsleutels hiermee. Hoofdstuk 2.8, Installaties op één machine, legt uit wat deze beheerders zijn. De beheerder bewaart de privéhelft offline en op een veilige plek: zonder deze helft kan niemand de sleutelkluis na een herstart ontzegelen.

Wat er gebeurt, van inschakelen tot het consoleadres

Fase één: het besturingssysteem

Het image start op in een onbeheerd Debian-installatieprogramma. Het configureert geen netwerk, gebruikt geen mirror en installeert geen enkel pakket buiten het basissysteem. Het stelt de tijdzone in op UTC (Coordinated Universal Time), schakelt aanmelden als root uit en maakt één gebruiker aan, nexus, waarvan het wachtwoord is vergrendeld. Het kiest de doelschijf volgens de bovenstaande regel en schrijft een GPT-schijf (globally unique identifier partition table) met een EFI-systeempartitie (Extensible Firmware Interface) en één ext4-rootbestandssysteem, zonder swap.

Aan het einde kopieert het het Nexus-installatieprogramma naar het nieuwe systeem, controleert het elk gekopieerd bestand aan de hand van de controlegetallenlijst van het image en schakelt het een service voor het eerste opstarten in. Als een gekopieerd bestand niet overeenkomt, stopt het proces daar. Vervolgens werpt het het medium uit en start het opnieuw op.

Fase twee: het eerste opstarten

Bij het eerste opstarten wordt de service nexus-install één keer uitgevoerd. Elke stap schrijft uitvoer naar de console van de server en naar het journal, en registreert zichzelf als voltooid, zodat een nieuwe poging begint bij de eerste stap die nog niet is voltooid. De service als geheel mag maximaal vier uur draaien voordat systemd deze stopt, wat ruimte laat voor een trage schijf en een uur wachttijd voor de bundelstick.

  1. Preflight. De architectuur, de klok, het geheugen en de vrije schijfruimte, zoals in de bovenstaande tabel.
  2. Payload. De eigen bestanden van het installatieprogramma: eerst de handtekening op de controlegetallenlijst met de meegeleverde releasesleutel, en daarna elk bestand aan de hand van die lijst.
  3. Seed. Leest seed.yaml en vraagt op de console naar alles wat ontbreekt.
  4. Bundle. Zoekt het volume met het label NEXUS-BUNDLE en koppelt dit aan als alleen-lezen. Als er geen volume is, meldt het waiting-for-bundle en wacht het maximaal een uur tot u het aansluit. Vervolgens voert het de volledige bundelcontrole uit, eindigend op VERIFY-BUNDLE PASS, met de meegeleverde releasesleutel, voordat er ook maar iets wordt geïmporteerd. Een Enterprise-bundel vereist licence.json op de seed, en de editie van de seed moet overeenkomen met die van de bundel.
  5. k3s. Installeert k3s v1.33.6+k3s1 vanuit de eigen bestanden van het image met uitgeschakelde downloads, en wacht maximaal tien minuten tot de node de status Ready heeft. Daarna verwijdert het het air-gap-imagearchief van k3s, zodat de images niet bij elke start opnieuw worden geïmporteerd.
  6. Import. Importeert elk geverifieerd image uit de bundel, evenals de images van cert-manager, in de containeropslag van de node. Er wordt nooit iets opgehaald uit een registry.
  7. cert-manager, daarna Nexus. Installeert cert-manager v1.21.3 en vervolgens de Nexus-chart uit de bundel, beide binnen de timeout van de seed.
  8. Acceptance. Controleert of elke pod de status Running heeft en elke hook-Job is voltooid.
  9. Credential. Geeft de besturingssysteemgebruiker nexus een nieuw willekeurig wachtwoord, toont dit eenmalig op de console en schrijft het naar nexus-os-password.txt op het seed-volume wanneer dat volume beschrijfbaar is.

De bundelcontrole in stap 4 is hetzelfde script dat u handmatig uitvoert in hoofdstuk 2.10, Air-gapped installatie, en geeft dezelfde regels weer:

  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>

Regel 3 telt de images die voorzien zijn van een geldige handtekening en een ondertekende SBOM (software bill of materials), de lijst met wat elk image bevat. De aantallen (<n>) zijn afhankelijk van de editie. Waar het om gaat, is de laatste regel.

De installatie schrijft waarden weg in de huidige structuur van de chart: global.domain en de drie hosts.*-namen uit het domein van de seed, en keys.custody.recipients van de beheerder die u op de console hebt opgegeven. Het installeert vanuit de eigen chart en images van de bundel, zodat de release op de schijf exact de release is die is gecontroleerd.

Een horizontale reeks van negen vakken: Preflight, Payload, Seed, Bundle, k3s, Import, cert-manager en Nexus, Acceptance, Credential. Onder elk vak toont een kort rood label wat de stap stopt: "geheugen, schijf, klok, architectuur", "handtekening of controlegetal", "geen domein of e-mailadres; geen licentie voor Enterprise", "geen NEXUS-BUNDLE binnen 1 u; VERIFY-BUNDLE FAIL", "node niet Ready binnen 10 min", "een image kan niet worden geïmporteerd", "helm install mislukt binnen de time-out", "een pod draait niet, een Job is niet voltooid", en niets onder Credential. Een terugkeerpijl vanaf elk vak naar het begin van de reeks heeft het label "nexus-install retry hervat bij de eerste onvoltooide stap".
Het eerste opstarten van het installatie-image, stap voor stap, waarbij elke stap de installatie kan stoppen.

De laatste regels op de console

Wanneer elke stap is geslaagd, toont de console eenmalig het wachtwoord van het besturingssysteem en het te openen adres:

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)

Noteer het wachtwoord of haal het van de seed-stick, meld u vervolgens aan als nexus en wijzig het met passwd. Niemand, ook Adverant niet, kent een standaardwachtwoord voor deze machine, omdat dat er niet is.

Het adres in de hosts-regel is het eigen adres van de server. Omdat er op de kade geen DNS (Domain Name System) was, voegde Tomás die ene regel toe aan het hosts-bestand van elke laptop die de console zou gaan gebruiken. Voeg op een locatie met DNS in plaats daarvan records toe voor de drie namen.

Gereed, of nog niet
Gereed, of nog niet
Na de installatie bevat de gereedheidslijst een test voor uitgaand verkeer, zodat een operator kan aantonen dat er in het afgelopen uur niets heeft geprobeerd naar buiten te gaan.

Na de installatie

De installatie is nog niet geclaimd. Niemand kan zich aanmelden totdat iemand de installatie in een browser claimt en daarbij de vingerafdruk van de installatie vergelijkt met die op de server. Hoofdstuk 2.12, Het eerste gebruik, behandelt het claimen, de eerste beheerder en de passkey. De eerste beheerder hoort de persoon te zijn van wie het e-mailadres in de seed staat.

De eigen kubeconfig van de node staat op /etc/rancher/k3s/k3s.yaml en is alleen leesbaar voor root. Om vanaf een werkstation op het cluster te werken, kunt u deze afdrukken met nexusctl kubeconfig, zoals beschreven in hoofdstuk 2.8, Installaties op één machine.

Updates komen op dezelfde manier binnen als de installatie: als een release op ondertekende media, gecontroleerd aan de hand van de sleutel die al op de server is geïnstalleerd en nooit aan de hand van een sleutel die de schijf zelf meebrengt. Hoofdstuk 2.10, Air-gapped installatie, beschrijft die controle.

Deze installatie claimen
Deze installatie claimen
De claimpagina die volgt op de installatie. De vingerafdruk wordt weergegeven in acht groepen van vier, om regel voor regel te vergelijken met de console van de server.

Als dit mislukt

Elke fout drukt nexus-install: FAILED <step>: <what is missing> af op de console en schrijft hetzelfde weg naar /var/lib/nexus/install.state. Verhelp de oorzaak en voer de installatie opnieuw uit vanaf de eerste stap die nog niet is voltooid:

sudo nexus-install retry
Bericht Wat het betekent Wat te doen
FAILED preflight: payload is for arm64, this machine is amd64 U hebt het image van de andere architectuur opgestart. Gebruik het image voor de architectuur van deze machine.
FAILED preflight: memory 11 GiB, need >= 16 GiB De machine heeft minder dan de ondergrens. Voeg geheugen toe, of wijs meer toe aan de VM.
FAILED preflight: free disk 38 GB on /, need >= 50 GB Het rootbestandssysteem is te klein. Installeer op een grotere schijf.
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed De hardwareklok loopt achter op de datum waarop het installatieprogramma is gebouwd. Stel de klok in via de firmware, of geef time op in seed.yaml, en probeer het opnieuw.
FAILED payload: SHA256SUMS signature does not verify De eigen bestanden van het installatieprogramma komen niet overeen met wat Adverant heeft ondertekend. Stop. Download het image opnieuw en controleer het voordat u het wegschrijft.
FAILED seed: the installation domain and the first administrator e-mail are required Noch de seed, noch de console heeft deze opgegeven. Voeg ze toe aan seed.yaml of beantwoord de vragen op het scherm.
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) De bundel is voor Enterprise en de seed bevat geen licentie. Plaats licence.json op het seed-volume.
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h Er is niet op tijd een bundel aangesloten. Sluit de bundelstick aan en probeer het opnieuw.
FAILED bundle: the bundle does not verify with this installer's release key De bundelcontrole eindigde niet met VERIFY-BUNDLE PASS. De eigen uitvoer ervan, boven de melding, noemt de betreffende stap. Stop. Gebruik die bundel niet. Haal een nieuwe op.
FAILED bundle: the seed asks for enterprise, the bundle is community De seed en de bundel spreken elkaar tegen. Corrigeer edition in de seed of gebruik de juiste bundel.
FAILED k3s: node not Ready within 10 min k3s is niet opgekomen. Controleer het journal voor k3s en probeer het vervolgens opnieuw.
FAILED nexus: helm install nexus De chart is niet binnen de time-out geïnstalleerd. Kijk naar kubectl -n nexus get pods,jobs, verhoog timeout in de seed als de machine traag is, en probeer het opnieuw.
FAILED acceptance: pods not ready Sommige pods draaien niet na de installatie. De melding noemt er maximaal vijf. Lees hun events, los het probleem op en probeer het opnieuw.
FAILED acceptance: jobs not complete: <jobs> Een hook-Job is niet voltooid. Lees het logboek van de genoemde Job met kubectl -n nexus logs job/<name>, los op wat daar wordt gemeld en probeer het opnieuw.

Voordat het besturingssysteem wordt geschreven, kan ook de schijfkeuze de installatie stoppen. Die melding begint met nexus select-disk: REFUSED:. De meest voorkomende is found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Noem de schijf in de seed en start opnieuw op.

Een mislukte bundelcontrole moet u zeer serieus nemen. Dit betekent dat de bestanden op de schijf niet de bestanden zijn die Adverant heeft ondertekend, of dat er een bestand is toegevoegd. Het installatieprogramma heeft op dat moment nog niets geïmporteerd, dus de server is ongewijzigd. Bewaar de schijf voor uw beveiligingsteam.