Log indBook en briefing

Kapitel 2.9

Installationsdiskafbildningen

Start en tom server eller en virtuel maskine fra Nexus-installationsafbildningen, og den installerer styresystemet, k3s, cert-manager og Nexus uden netværk, idet hver fil kontrolleres, før den tages i brug.

Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

17 minutters læsetid

Havnefogedens kontor på Harrows østkaj har én server, intet internet og ingen på stedet, der driver Kubernetes. Tomás Reilly skulle alligevel have Nexus på den. Han skrev diskbilledet til et USB-stik (Universal Serial Bus), satte et andet, lille stik ved siden af med fire linjer indstillinger og startede serveren op. En time senere viste skærmen konsollens adresse og de tre linjer, der skulle føjes til hosts-filen. Han tastede ikke en eneste Kubernetes-kommando.

Det er den opgave, installationsdiskbilledet løser. Det skriver et minimalt styresystem til serverens disk, og ved første opstart kontrollerer det hver eneste medbragte fil mod Adverant-udgivelsesnøglen, installerer k3s uden netværk, importerer alle billeder, installerer cert-manager og Nexus og kontrollerer, at hver pod kører. Hvert trin stopper med en navngiven årsag i samme øjeblik, noget er galt. Der er ingen nedgraderet drift og ingen standardadgangskode nogetsteds.

De to afbildninger

Hver udgivelse leveres som to slags billeder til to processorarkitekturer, amd64 og arm64.

Fil Hvad den indeholder Hvem der kan hente det
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso Kun installationsprogrammet: styresystemet, k3s v1.33.6+k3s1, cert-manager v1.21.3 og installationsprogrammet til første opstart. Det virker til begge udgaver og indeholder ingen Nexus-billeder. Alle, fra downloads.adverant.ai
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso Samme installationsprogram med den pågældende udgaves offline-pakke tilføjet som en anden partition med navnet NEXUS-BUNDLE. Ét medie installerer alt. Community: alle. Enterprise: kun fra Deres Adverant-konto

<arch> er amd64 eller arm64, og <edition> er community eller enterprise.

Installationsprogrammet leder udelukkende efter et filsystem med navnet NEXUS-BUNDLE. I alt-i-et-billedet er det partitionen på selve billedet. Med billedet, der kun indeholder installationsprogrammet, medbringer De pakken på en anden disk eller et andet stik med det navn, hvilket er praktisk, når De installerer flere lokationer fra ét installationsstik og kun udskifter pakken. Kapitel 2.10, Air-gapped installation, beskriver pakken.

Enterprise-billeder og Enterprise-pakker er aldrig anonyme. De henter dem fra Deres Adverant-konto på https://account.adverant.ai, på siden Downloads, ved siden af Deres licens. Community-billeder og -pakker er offentlige.

To disktegninger er placeret side om side. Den venstre, "billede med kun installationsprogram", har én partition med teksten "installationsprogram til styresystem, k3s, cert-manager, installationsprogram til første opstart" og ved siden af den et separat USB-stik med teksten "NEXUS-BUNDLE: udgavens offline-pakke". Den højre, "alt-i-et-billede", har den samme første partition og en anden partition på samme disk med teksten "NEXUS-BUNDLE". Under begge har et lille USB-stik teksten "NEXUS-SEED: seed.yaml, og licence.json til Enterprise", med en bemærkning "valgfrit for Community". Pile fra alle tre tekster peger ned mod én boks, "første opstart finder hver del ud fra dens navn".
Billedet med kun installationsprogrammet og alt-i-et-billedet, og hvor første opstart finder hver del.

Hvad billedet er bygget af

Styresystemet er baseret på Debian 13 og er ikke et officielt Debian-billede. Det indeholder Debians basissystem og intet andet: ingen ekstra pakker, intet skrivebordsmiljø og intet pakkespejl. k3s medbringer sin egen container-runtime og sit eget netværk. Opstartskæden (shim, GRUB, kernen og den indledende ramdisk) er byte for byte den, Debian leverer, så en maskine med Secure Boot slået til starter det som ethvert andet Debian-installationsprogram.

To oversættelser af samme udgivelse giver identiske billeder, byte for byte, og udgivelsen offentliggøres ikke, før de gør det. Debian-kildepakkerne til hver binær fil på billedet offentliggøres ved siden af det som nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, i den samme tjeksumsliste.

Kontroller den hentede fil, før De skriver den

Billedmappen på downloads.adverant.ai indeholder billederne, en SHA256SUMS-fil, der dækker samtlige offentliggjorte filer, og SHA256SUMS.sigstore.json, signaturen over den liste lavet med Adverant-udgivelsesnøglen. Hent den offentlige udgivelsesnøgle separat, gem den som release.pub, og kontrollér dens fingeraftryk som beskrevet i kapitel 2.4, Sådan hentes og verificeres en udgivelse.

  1. Verificér signaturen på tjeksumslisten. Der er ingen transparenslog for Nexus-udgivelser, så flaget, der springer logopslaget over, er påkrævet.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. Kontrollér det billede, De har hentet, mod listen:
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

På en Mac bruges shasum -a 256 -c - i stedet for sha256sum -c -.

  1. Skriv billedet til et USB-stik med det værktøj, De normalt bruger, eller tilknyt det til den virtuelle maskine som en optisk disk.

k3s offentliggør tjeksummer for sine udgivelsesfiler og ingen signatur, så k3s-filerne inde i billedet kontrolleres mod de tjeksummer, k3s offentliggør, fra samme kilde som filerne. Alt, hvad Adverant har bygget, er signeret.

Pakker i dele

En pakke, De medbringer på et separat stik, fylder adskillige gigabyte. Nogle filsystemer, heriblandt FAT (File Allocation Table), kan ikke rumme en fil på 4 GiB eller mere, så pakkefiler offentliggøres i dele på 2047 MiB, der kan være på ethvert stik. Saml delene igen i rækkefølge, og kontrollér den samlede fil mod dens .sha256, før De bruger den.

Den nødvendige hardware

Den første opstart kontrollerer maskinen, før den rører ved noget, og nægter at fortsætte, når maskinen er for lille.

Kontrol Bunden Hvornår det kontrolleres
Arkitektur Billedets egen: et amd64-billede på amd64, arm64 på arm64 Første opstart
Hukommelse 16 GiB Første opstart
Destinationsdisk Præcis én tom disk på mindst 64 GB, eller den disk, som seed-filen angiver Før styresystemet skrives
Ledig plads på / 50 GB efter at styresystemet er på plads Første opstart
Ur Ikke ældre end den dato, hvor billedet blev bygget Første opstart

Disse tal er absolutte minimumskrav, ikke en anbefaling. Med chartets standardindstillinger løber Nexus' diskenheder alene op i 142 GiB, så en disk på 64 GB slipper igennem installationsprogrammet og fyldes op i løbet af få dage. Brug det, en enkelt node bør have: 8 vCPU (virtual central processing units), 32 GiB hukommelse og en 250 GB SSD (solid-state drive). Fire vCPU, 16 GiB og 200 GB er nok til en evaluering.

Kontrollen af uret er der, fordi serveren ikke har noget netværk og dermed ingen tidstjeneste under installationen. Certifikater og signaturer kontrolleres mod uret. Hvis maskinens hardwareur er bagud i forhold til billedets byggedato, stopper den første opstart og beder Dem om at indstille det. Indstil det i firmwareopsætningen, og start op igen.

Fysiske servere og virtuelle maskiner

Billedet starter op på UEFI-firmware (Unified Extensible Firmware Interface), på fysiske servere såvel som på virtuelle maskiner. Det installerer bootloaderen på stien til flytbare medier såvel som på den sædvanlige sti, så en VM (virtual machine) uden gemte opstartsposter stadig finder den efter den første genstart. Giv en VM den hukommelse og diskplads, der er angivet i tabellen ovenfor, én tom virtuel disk og billedet som en cd.

Installationsprogrammet vælger destinationsdisken efter en streng regel og vælger aldrig blot "den første disk".

  • Det springer det medie over, som det startede op fra.
  • Det springer flytbare diske over, medmindre seed-filen angiver en.
  • Det springer enhver disk over, der allerede har en partitionstabel, uanset type.
  • Det springer diske under 64 GB over og oplyser dette på konsollen.
  • Det installerer kun, når der er præcis én disk tilbage.

På en server med to tomme diske stopper det og beder Dem om at vælge. De vælger ved at angive disken i seed-filen med wipe: true, hvilket er den eneste måde, hvorpå det nogensinde vil skrive til en disk, der allerede har partitioner.

NEXUS-SEED-diskenheden

Seed-mediet er en lille diskenhed, normalt et USB-stik, med et filsystem navngivet NEXUS-SEED og en fil seed.yaml på øverste niveau. Installationsprogrammet monterer det skrivebeskyttet, læser indstillingerne og genmonterer det kun skrivbart til allersidst for at efterlade adgangskoden til styresystemet til Dem.

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
Nøgle Hvad den indstiller Når den mangler
domain Installationens domæne. Installationsprogrammet udleder de tre værtsnavne fra det: console.<domain>, api.<domain> og auth.<domain>. Spørges om på serverens konsol
adminEmail E-mailadressen på den person, der skal være den første administrator Spørges om på serverens konsol
edition community eller enterprise. Når den er indstillet, skal den svare til pakkens udgave. Hentes fra pakken
timeout Hvor lang tid installationen af cert-manager og Nexus må tage, angivet som en varighed såsom 30m eller 1h 30m
time Det aktuelle klokkeslæt i UTC, i det format som urmeddelelsen udskriver (2026-11-14T09:00:00Z), til en maskine, hvis hardwareur ikke kan indstilles eller ikke holder sin indstilling. En offline-maskine har ingen tidsserver at spørge. Hardwareuret bruges
disk Destinationsdisken, som /dev/<name>, bruges kun sammen med wipe: true Reglen om tom disk ovenfor
wipe true lader installationsprogrammet slette den disk, som disk angiver Ingen disk slettes nogensinde

Til Enterprise skal De lægge licensfilen på samme diskenhed som licence.json. Uden den stopper første opstart ved seed-trinnet og meddeler, at licensen mangler. Community kræver ingen licens, og for Community er hele seed-mediet valgfrit: installationsprogrammet spørger efter domænet og e-mailadressen på konsollen og fortsætter.

Installationsprogrammet læser hver linje som key: value i starten af linjen. Skriv én nøgle pr. linje på øverste niveau uden anførselstegn og uden indrykning. En værdi i anførselstegn læses med sine anførselstegn.

Ved første opstart spørger installationsprogrammet også på konsollen efter nøglelagerets nøgleforvalter (custodian): den offentlige halvdel af en age-nøgle, age1..., oprettet på nøgleforvalterens egen maskine med age-keygen -o custodian.key. Nøglelageret forsegler sine gendannelsesnøgler til den. Kapitel 2.8, Installation på en enkelt maskine, forklarer nøgleforvaltere. Nøgleforvalteren opbevarer den private halvdel offline og sikkert: uden den kan ingen åbne nøglelagerets forsegling efter en genstart.

Hvad der sker, fra opstart til konsoladressen

Fase et: styresystemet

Billedet starter op i et ubemandet Debian-installationsprogram. Det konfigurerer ikke et netværk, bruger ikke et pakkespejl og installerer ingen pakker ud over basissystemet. Det indstiller tidszonen til UTC (Coordinated Universal Time), deaktiverer root-login og opretter én bruger, nexus, hvis adgangskode er låst. Det vælger destinationsdisken efter reglen ovenfor og skriver en GPT-disk (globally unique identifier partition table) med en EFI-systempartition (Extensible Firmware Interface) og ét ext4-rodfilsystem uden swap.

Til sidst kopierer det Nexus-installationsprogrammet over på det nye system, kontrollerer hver kopieret fil mod billedets tjeksumsliste og aktiverer en tjeneste til første opstart. Hvis en kopieret fil ikke stemmer overens, stopper det dér. Derefter skubber det mediet ud og genstarter.

Fase to: den første opstart

Ved første opstart kører tjenesten nexus-install én gang. Hvert trin udskriver til serverens konsol og til journalen og registrerer sig selv som udført, så et nyt forsøg starter fra det første trin, der ikke er udført. Tjenesten som helhed kan køre i op til fire timer, før systemd stopper den, hvilket giver plads til en langsom disk og en times ventetid på pakkestikket.

  1. Preflight. Arkitekturen, uret, hukommelsen og den ledige diskplads, som i tabellen ovenfor.
  2. Payload. Installationsprogrammets egne filer: signaturen på dets tjeksumsliste med den udgivelsesnøgle, det medbringer, og derefter hver fil mod den liste.
  3. Seed. Læser seed.yaml og spørger på konsollen om alt, der mangler.
  4. Bundle. Finder diskenheden med navnet NEXUS-BUNDLE og monterer den skrivebeskyttet. Hvis der ikke er en, udskriver den waiting-for-bundle og venter i op til en time på, at De tilslutter den. Derefter kører den den fulde pakkekontrol, der slutter med VERIFY-BUNDLE PASS, med den udgivelsesnøgle, den medbringer, før noget importeres. En Enterprise-pakke kræver licence.json på seed-mediet, og seed-mediets udgave skal svare til pakkens.
  5. k3s. Installerer k3s v1.33.6+k3s1 fra billedets egne filer med downloads slået fra og venter i op til ti minutter på, at noden bliver Ready. Derefter fjerner det k3s-air-gap-billedarkivet, så billederne ikke importeres igen ved hver opstart.
  6. Import. Importerer hvert verificeret billede fra pakken samt cert-managers billeder til nodens containerlager. Intet hentes nogensinde fra et register.
  7. cert-manager, derefter Nexus. Installerer cert-manager v1.21.3 og derefter Nexus-chartet fra pakken, begge inden for seed-mediets timeout.
  8. Acceptance. Kontrollerer, at hver pod har status Running, og at hvert hook-Job er fuldført.
  9. Credential. Giver styresystembrugeren nexus en ny tilfældig adgangskode, viser den én gang på konsollen og skriver den til nexus-os-password.txt på seed-diskenheden, når der kan skrives til diskenheden.

Pakkekontrollen i trin 4 er det samme script, som De kører manuelt i kapitel 2.10, Air-gapped installation, og det udskriver de samme linjer:

  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>

Linje 3 tæller de billeder, der bærer en gyldig signatur og en signeret SBOM (software bill of materials), listen over hvad hvert billede indeholder. Antallene (<n>) afhænger af udgaven. Det afgørende er den sidste linje.

Installationen skriver værdier i chartets aktuelle form: global.domain og de tre hosts.*-navne fra seed-mediets domæne samt keys.custody.recipients fra den nøgleforvalter, De angav på konsollen. Den installerer fra pakkens eget chart og egne billeder, så udgivelsen på disken er nøjagtig den udgivelse, der blev kontrolleret.

En vandret kæde med ni bokse: Preflight, Payload, Seed, Bundle, k3s, Import, cert-manager og Nexus, Acceptance, Credential. Under hver boks viser en kort rød tekst, hvad der stopper den: "hukommelse, disk, ur, arkitektur", "signatur eller tjeksum", "intet domæne eller e-mail; ingen licens til Enterprise", "ingen NEXUS-BUNDLE inden for 1 t.; VERIFY-BUNDLE FAIL", "node ikke Ready inden for 10 min.", "et billede kan ikke importeres", "helm install fejler inden for tidsgrænsen", "en pod kører ikke, et Job er ikke fuldført", og intet under Credential. En returpil fra hver boks til kædens start har teksten "nexus-install retry genoptager ved det første trin, der ikke er udført".
Den første opstart af installationsbilledet, trin for trin, hvor hvert trin kan stoppe installationen.

De sidste linjer på konsollen

Når hvert trin er gennemført, viser konsollen adgangskoden til styresystemet én gang samt den adresse, der skal åbnes:

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)

Skriv adgangskoden ned, eller hent den fra seed-stikket, log derefter ind som nexus, og skift den med passwd. Ingen, heller ikke Adverant, kender en standardadgangskode til denne maskine, for der findes ikke en.

Adressen i hosts-linjen er serverens egen. Da der ikke var noget DNS (Domain Name System) på kajen, tilføjede Tomás den ene linje til hosts-filen på hver bærbar computer, der skulle bruge konsollen. På en lokation med DNS skal De i stedet tilføje poster for de tre navne.

Klar, eller ikke endnu
Klar, eller ikke endnu
Efter installationen indeholder klarmeldingslisten en test af udgående trafik, så en operatør kan påvise, at intet har forsøgt at forlade maskinen i den seneste time.

Efter installationen

Installationen er endnu ikke overtaget. Ingen kan logge ind, før nogen gør krav på den i en browser ved at sammenligne installationens fingeraftryk med det, serveren viser. Kapitel 2.12, Den første kørsel, gennemgår overtagelsen, den første administrator og adgangsnøglen (passkey). Den første administrator bør være den person, hvis e-mailadresse står i seed-filen.

Nodens egen kubeconfig ligger på /etc/rancher/k3s/k3s.yaml og kan kun læses af root. For at arbejde på klyngen fra en arbejdsstation kan nexusctl kubeconfig udskrive den, som beskrevet i kapitel 2.8, Installation på en enkelt maskine.

Opdateringer ankommer på samme måde som selve installationen: en udgivelse på et signeret medie, kontrolleret mod den nøgle, der allerede er installeret på serveren, og aldrig mod en nøgle, som disken selv medbringer. Kapitel 2.10, Air-gapped installation, beskriver denne kontrol.

Overtag denne installation
Overtag denne installation
Overtagelsessiden, der følger efter installationen. Fingeraftrykket vises i otte grupper af fire, så det kan sammenlignes med serverens konsol linje for linje.

Hvis dette fejler

Enhver fejl udskriver nexus-install: FAILED <step>: <what is missing> på konsollen og skriver det samme i /var/lib/nexus/install.state. Ret årsagen, og kør installationen igen fra det første trin, der ikke er udført:

sudo nexus-install retry
Besked Hvad det betyder Hvad du skal gøre
FAILED preflight: payload is for arm64, this machine is amd64 De startede billedet til den anden arkitektur op. Brug billedet til denne maskines arkitektur.
FAILED preflight: memory 11 GiB, need >= 16 GiB Maskinen har mindre end minimumskravet. Tilføj hukommelse, eller giv VM'en mere.
FAILED preflight: free disk 38 GB on /, need >= 50 GB Rodfilsystemet er for lille. Installér på en større disk.
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed Hardwareuret er bagud i forhold til den dato, hvor installationsprogrammet blev bygget. Indstil uret i firmwaren, eller angiv time i seed.yaml, og prøv igen.
FAILED payload: SHA256SUMS signature does not verify Installationsprogrammets egne filer er ikke det, Adverant signerede. Stop. Hent billedet igen, og kontrollér det før skrivning.
FAILED seed: the installation domain and the first administrator e-mail are required Hverken seed-filen eller konsollen angav dem. Føj dem til seed.yaml, eller besvar spørgsmålene på konsollen.
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) Pakken er Enterprise, og seed-mediet har ingen licens. Læg licence.json på seed-diskenheden.
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h Ingen pakke blev tilsluttet i tide. Tilslut pakkestikket, og prøv igen.
FAILED bundle: the bundle does not verify with this installer's release key Pakkekontrollen sluttede ikke med VERIFY-BUNDLE PASS. Dens eget output, over meddelelsen, angiver trinnet. Stop. Brug ikke den pakke. Skaf en ny.
FAILED bundle: the seed asks for enterprise, the bundle is community Seed-mediet og pakken stemmer ikke overens. Ret edition i seed-filen, eller medbring den rigtige pakke.
FAILED k3s: node not Ready within 10 min k3s startede ikke op. Kontrollér journalen for k3s, og prøv derefter igen.
FAILED nexus: helm install nexus Chartet blev ikke installeret inden for tidsgrænsen. Se på kubectl -n nexus get pods,jobs, hæv timeout i seed-filen, hvis maskinen er langsom, og prøv igen.
FAILED acceptance: pods not ready Nogle pods kører ikke efter installationen. Meddelelsen nævner op til fem. Læs deres hændelser, ret fejlen, og prøv igen.
FAILED acceptance: jobs not complete: <jobs> Et hook-Job er ikke blevet færdigt. Læs det nævnte Jobs log med kubectl -n nexus logs job/<name>, ret det, den rapporterer, og prøv igen.

Før styresystemet skrives, kan diskvalget også stoppe installationen. Dets meddelelse starter med nexus select-disk: REFUSED:. Den almindelige er found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Angiv disken i seed-filen, og start op igen.

En mislykket pakkekontrol er den fejl, man skal tage alvorligt. Det betyder, at filerne på disken ikke er de filer, Adverant har signeret, eller at en fil er blevet tilføjet. Installationsprogrammet har på det tidspunkt ikke importeret noget, så serveren er uændret. Gem disken til Deres sikkerhedsteam.