Logg innBestill en gjennomgang

Kapittel 2.9

Diskavbildningen for installasjonsprogrammet

Start opp en tom server eller en virtuell maskin fra installasjonsavbildningen for Nexus, så installerer den operativsystemet, k3s, cert-manager og Nexus uten nettverk, og kontrollerer hver fil før den brukes.

Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

17 minutter å lese

Havnekapteinskontoret på Harrows østkai har én server, intet internett og ingen på stedet som drifter Kubernetes. Tomás Reilly trengte likevel Nexus på den. Han skrev diskbildet til en USB-minnepinne (Universal Serial Bus), satte inn en annen, liten minnepinne ved siden av med fire linjer med innstillinger, og startet opp serveren. En time senere viste skjermen konsollens adresse og de tre linjene som måtte legges til i hosts-filen. Han skrev ikke en eneste Kubernetes-kommando.

Det er jobben til installasjonsdiskbildet. Det skriver et minimalt operativsystem til serverens disk, og ved første oppstart sjekker det hver fil det har med seg mot Adverants utgivelsesnøkkel, installerer k3s uten nettverk, importerer hvert bilde, installerer cert-manager og Nexus, og kontrollerer at hver pod kjører. Hvert trinn stopper med en navngitt årsak i det øyeblikket noe er galt. Det finnes ingen degradert kjørevei og ikke noe standardpassord noe sted.

De to avbildningene

Hver utgivelse leveres som to typer diskbilder, for to prosessorarkitekturer: amd64 og arm64.

Fil Hva den inneholder Hvem som kan laste det ned
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso Kun installasjonsprogrammet: operativsystemet, k3s v1.33.6+k3s1, cert-manager v1.21.3 og installasjonsprogrammet for første oppstart. Det fungerer for begge utgaver og inneholder ingen Nexus-bilder. Alle, fra downloads.adverant.ai
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso Det samme installasjonsprogrammet med den aktuelle utgavens frakoblede pakke lagt til som en andre partisjon merket NEXUS-BUNDLE. Ett medium installerer alt. Community: alle. Enterprise: kun fra din Adverant-konto

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

Installasjonsprogrammet ser kun etter et filsystem merket NEXUS-BUNDLE. I alt-i-ett-bildet er det partisjonen på selve diskbildet. Med bildet som kun inneholder installasjonsprogrammet, tar du med pakken på en annen disk eller minnepinne med det merket, noe som er praktisk når du installerer flere lokasjoner fra én installasjonsminnepinne og kun bytter ut pakken. Kapittel 2.10, Frakoblet installasjon (air-gapped), beskriver pakken.

Enterprise-bilder og Enterprise-pakker er aldri anonyme. Du laster dem ned fra din Adverant-konto på https://account.adverant.ai, på nedlastingssiden (Downloads), ved siden av lisensen din. Community-bilder og -pakker er offentlige.

To disktegninger ligger side om side. Den venstre, «bilde kun med installasjonsprogram», har én partisjon merket «installasjonsprogram for operativsystem, k3s, cert-manager, installasjonsprogram for første oppstart» og ved siden av den en separat USB-minnepinne merket «NEXUS-BUNDLE: utgavens frakoblede pakke». Den høyre, «alt-i-ett-bilde», har den samme første partisjonen og en andre partisjon på samme disk merket «NEXUS-BUNDLE». Under begge er en liten USB-minnepinne merket «NEXUS-SEED: seed.yaml, og licence.json for Enterprise», med et notat «valgfritt for Community». Piler fra alle tre etikettene peker ned til én boks, «første oppstart finner hver enkelt etter etiketten».
Bildet med kun installasjonsprogrammet og alt-i-ett-bildet, og hvor første oppstart finner hver del.

Hva diskbildet er bygget av

Operativsystemet er basert på Debian 13 og er ikke et offisielt Debian-bilde. Det inneholder Debians grunnsystem og ingenting annet: ingen ekstra pakker, intet skrivebordsmiljø og intet pakkespeil. k3s har med sin egen kjøretidsmotor for containere og sitt eget nettverk. Oppstartskjeden (shim, GRUB, kjernen og initial ramdisk) er byte for byte den samme som Debian leverer, slik at en maskin med Secure Boot påslått starter den som enhver Debian-installasjon.

To bygg av samme utgivelse gir identiske diskbilder, byte for byte, og utgivelsen publiseres ikke før de gjør det. Debian-kildepakkene for hver binærfil på diskbildet publiseres ved siden av det som nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, i den samme sjekksumlisten.

Kontroller nedlastingen før du skriver den

Bildekatalogen på downloads.adverant.ai inneholder diskbildene, en SHA256SUMS-fil som dekker hver publiserte fil, og SHA256SUMS.sigstore.json, signaturen over den listen laget med Adverants utgivelsesnøkkel. Hent den offentlige utgivelsesnøkkelen separat, lagre den som release.pub, og kontroller fingeravtrykket slik kapittel 2.4, Hente og verifisere en utgivelse, beskriver.

  1. Verifiser signaturen på sjekksumlisten. Det er ingen transparenslogg for Nexus-utgivelser, så flagget som hopper over loggoppslaget er påkrevd.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. Kontroller diskbildet du lastet ned mot 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 bruker du shasum -a 256 -c - i stedet for sha256sum -c -.

  1. Skriv diskbildet til en USB-minnepinne med verktøyet du vanligvis bruker, eller koble det til den virtuelle maskinen som en optisk plate.

k3s publiserer sjekksummer for utgivelsesfilene sine og ingen signatur, så k3s-filene inne i diskbildet kontrolleres mot sjekksummene k3s publiserer, fra samme opprinnelse som filene. Alt Adverant har bygget, er signert.

Pakker i deler

En pakke du har med på en separat minnepinne, er på flere gigabyte. Enkelte filsystemer, deriblant FAT (File Allocation Table), kan ikke lagre en fil på 4 GiB eller mer, så pakkefiler publiseres i deler på 2047 MiB som får plass på enhver minnepinne. Sett delene sammen igjen i riktig rekkefølge og kontroller den sammensatte filen mot dens .sha256 før du bruker den.

Maskinvaren som kreves

Første oppstart kontrollerer maskinen før den rører noe som helst, og nekter å fortsette når maskinen er for liten.

Kontroll Grunnflaten Når det kontrolleres
Arkitektur Diskbildets egen: et amd64-bilde på amd64, arm64 på arm64 Første oppstart
Minne 16 GiB Første oppstart
Måldisk Nøyaktig én tom disk på minst 64 GB, eller disken som startkonfigurasjonen (seed) navngir Før operativsystemet skrives
Ledig plass på / 50 GB etter at operativsystemet er på plass Første oppstart
Klokke Ikke eldre enn datoen diskbildet ble bygget Første oppstart

Dette er absolutt minimum, ikke en anbefaling. Med standardverdiene i Helm-chartet utgjør Nexus-volumene alene 142 GiB, så en disk på 64 GB slipper gjennom installasjonsprogrammet og fylles opp i løpet av dager. Bruk det en enkelt node bør ha: 8 vCPU (virtuelle prosessorkjerner), 32 GiB minne og en 250 GB SSD (solid-state drive). Fire vCPU, 16 GiB og 200 GB er nok for en evaluering.

Klokkekontrollen er der fordi serveren ikke har nettverk, og dermed ingen tidstjeneste, under installasjonen. Sertifikater og signaturer sjekkes mot klokken. Hvis maskinens maskinvareklokke ligger etter diskbildets byggedato, stopper første oppstart og ber deg stille den. Still den i fastvareoppsettet (firmware) og start opp på nytt.

Fysiske servere og virtuelle maskiner

Diskbildet starter opp på UEFI-fastvare (Unified Extensible Firmware Interface), både på fysiske servere og på virtuelle maskiner. Det installerer oppstartslasteren (boot loader) på stien for flyttbare medier i tillegg til den vanlige, slik at en VM (virtuell maskin) uten lagrede oppstartsoppføringer likevel finner den etter første omstart. Gi en VM minnet og disken i tabellen ovenfor, én tom virtuell disk, og diskbildet som en CD.

Installasjonsprogrammet velger måldisken etter en streng regel og velger aldri bare «den første disken».

  • Det hopper over mediet det startet opp fra.
  • Det hopper over flyttbare disker, med mindre startkonfigurasjonen (seed) navngir en.
  • Det hopper over enhver disk som allerede har en partisjonstabell, uansett type.
  • Det hopper over disker under 64 GB, og sier fra om det på konsollen.
  • Det installerer kun når det er nøyaktig én disk igjen.

På en server med to tomme disker stopper det og ber deg velge. Du velger ved å navngi disken i startkonfigurasjonen (seed), med wipe: true, som er den eneste måten det noen gang vil skrive til en disk som allerede har partisjoner på.

NEXUS-SEED-volumet

Startkonfigurasjonen (seed) er et lite volum, vanligvis en USB-minnepinne, med et filsystem merket NEXUS-SEED og en fil seed.yaml på øverste nivå. Installasjonsprogrammet monterer det skrivebeskyttet, leser innstillingene, og monterer det skrivbart kun helt på slutten for å legge igjen operativsystempassordet til deg.

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
Nøkkel Hva den setter Når den mangler
domain Installasjonens domene. Installasjonsprogrammet utleder de tre vertene fra det: console.<domain>, api.<domain> og auth.<domain>. Spørres etter på serverens konsoll
adminEmail E-postadressen til personen som skal være den første administratoren Spørres etter på serverens konsoll
edition community eller enterprise. Når den er satt, må den samsvare med pakkens utgave. Hentes fra pakken
timeout Hvor lang tid installasjonen av cert-manager og Nexus kan ta, som en varighet som 30m eller 1h 30m
time Gjeldende tid i UTC, i formatet klokkemeldingen skriver ut (2026-11-14T09:00:00Z), for en maskin der maskinvareklokken ikke kan stilles eller ikke holder på innstillingen. En frakoblet maskin har ingen tidsserver å spørre. Maskinvareklokken brukes
disk Måldisken, som /dev/<name>, brukes kun sammen med wipe: true Regelen for tom disk ovenfor
wipe true lar installasjonsprogrammet slette disken som disk navngir Ingen disk slettes noen gang

For Enterprise legger du lisensfilen på samme volum som licence.json. Uten den stopper første oppstart på seed-trinnet og sier at lisensen mangler. Community trenger ingen lisens, og for Community er hele startkonfigurasjonen (seed) valgfri: installasjonsprogrammet spør etter domenet og e-postadressen på konsollen og fortsetter.

Installasjonsprogrammet leser hver linje som key: value på starten av linjen. Skriv én nøkkel per linje, på øverste nivå, uten anførselstegn og uten innrykk. En verdi i anførselstegn leses med anførselstegnene inkludert.

Ved første oppstart spør installasjonsprogrammet også på konsollen etter nøkkellagerets forvalter (custodian): den offentlige halvdelen av en age-nøkkel, age1..., laget på forvalterens egen maskin med age-keygen -o custodian.key. Nøkkellageret forsegler gjenopprettingsnøklene sine til den. Kapittel 2.8, Installasjoner på én maskin, forklarer forvaltere. Forvalteren oppbevarer den private halvdelen frakoblet og trygt: uten den kan ingen låse opp nøkkellageret etter en omstart.

Hva som skjer, fra oppstart til konsolladressen

Trinn én: operativsystemet

Diskbildet starter opp i en ubetjent Debian-installasjon. Den konfigurerer ikke nettverk, bruker ikke pakkespeil og installerer ingen pakker utover grunnsystemet. Den setter tidssonen til UTC (Coordinated Universal Time), deaktiverer root-innlogging, og oppretter én bruker, nexus, hvis passord er låst. Den velger måldisken etter regelen ovenfor og skriver en GPT-disk (globally unique identifier partition table) med en EFI-systempartisjon (Extensible Firmware Interface) og ett ext4-rotfilsystem, uten veksleminne (swap).

Til slutt kopierer den Nexus-installasjonsprogrammet over på det nye systemet, kontrollerer hver kopierte fil mot diskbildets sjekksumliste, og aktiverer en tjeneste for første oppstart. Hvis en kopiert fil ikke stemmer, stopper den der. Deretter løser den ut mediet og starter på nytt.

Trinn to: første oppstart

Ved første oppstart kjører tjenesten nexus-install én gang. Hvert trinn skrives ut til serverens konsoll og til journalen, og registrerer seg selv som fullført, slik at et nytt forsøk starter fra det første trinnet som ikke er fullført. Tjenesten som helhet kan kjøre i opptil fire timer før systemd stopper den, noe som gir rom for en treg disk og en times venting på minnepinnen med pakken.

  1. Forhåndskontroll (Preflight). Arkitekturen, klokken, minnet og ledig diskplass, som i tabellen ovenfor.
  2. Nyttelast (Payload). Installasjonsprogrammets egne filer: signaturen på sjekksumlisten med utgivelsesnøkkelen det har med seg, og deretter hver fil mot den listen.
  3. Startkonfigurasjon (Seed). Leser seed.yaml, og spør på konsollen etter alt som mangler.
  4. Pakke (Bundle). Finner volumet merket NEXUS-BUNDLE og monterer det skrivebeskyttet. Hvis det ikke finnes, sier den waiting-for-bundle og venter i opptil en time på at du skal koble det til. Deretter kjører den full pakkekontroll, som avsluttes med VERIFY-BUNDLE PASS, med utgivelsesnøkkelen den har med seg, før noe importeres. En Enterprise-pakke krever licence.json på startkonfigurasjonen (seed), og utgaven i startkonfigurasjonen må samsvare med pakkens.
  5. k3s. Installerer k3s v1.33.6+k3s1 fra diskbildets egne filer med nedlastinger slått av, og venter i opptil ti minutter på at noden skal bli klar (Ready). Deretter fjerner den det frakoblede k3s-bildearkivet, slik at bildene ikke importeres på nytt ved hver oppstart.
  6. Import. Importerer hvert verifiserte bilde fra pakken, samt bildene til cert-manager, inn i nodens containerlager. Ingenting hentes noen gang fra et register.
  7. cert-manager, deretter Nexus. Installerer cert-manager v1.21.3, deretter Nexus-chartet fra pakken, begge innenfor tidsfristen timeout fra startkonfigurasjonen.
  8. Godkjenning (Acceptance). Kontrollerer at hver pod har status Running og at hver hook-Job er fullført.
  9. Legitimasjon (Credential). Gir operativsystembrukeren nexus et nytt tilfeldig passord, viser det én gang på konsollen, og skriver det til nexus-os-password.txt på seed-volumet når volumet er skrivbart.

Pakkekontrollen i trinn 4 er det samme skriptet du kjører manuelt i kapittel 2.10, Frakoblet installasjon (air-gapped), og det skriver ut de samme linjene:

  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 teller bildene som har en gyldig signatur og en signert SBOM (software bill of materials), listen over hva hvert bilde inneholder. Antallene (<n>) avhenger av utgaven. Det som betyr noe, er den siste linjen.

Installasjonen skriver verdier i chartets nåværende form: global.domain og de tre hosts.*-navnene fra startkonfigurasjonens domene, samt keys.custody.recipients fra forvalteren du oppga på konsollen. Den installerer fra pakkens eget chart og egne bilder, slik at utgivelsen på disken er nøyaktig den utgivelsen som ble kontrollert.

En horisontal kjede med ni bokser: Preflight, Payload, Seed, Bundle, k3s, Import, cert-manager og Nexus, Acceptance, Credential. Under hver boks viser en kort rød etikett hva som stopper den: «minne, disk, klokke, arkitektur», «signatur eller sjekksum», «mangler domene eller e-post; mangler lisens for Enterprise», «ingen NEXUS-BUNDLE innen 1 t; VERIFY-BUNDLE FAIL», «node ikke Ready innen 10 min», «et bilde lar seg ikke importere», «helm install mislykkes innen tidsavbruddet», «en pod kjører ikke, en Job er ikke fullført», og ingenting under Credential. En returpil fra hver boks til starten av kjeden er merket «nexus-install retry gjenopptar ved første trinn som ikke er fullført».
Første oppstart av installasjonsbildet, ett trinn etter et annet, der hvert enkelt kan stoppe installasjonen.

De siste linjene på konsollen

Når hvert trinn er bestått, viser konsollen operativsystempassordet én gang samt adressen som skal åpnes:

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 ned passordet eller hent det fra seed-minnepinnen, logg deretter inn som nexus og endre det med passwd. Ingen, inkludert Adverant, kjenner et standardpassord for denne maskinen, fordi det ikke finnes noe.

Adressen i hosts-linjen er serverens egen. Uten DNS (Domain Name System) på kaien la Tomás til den ene linjen i hosts-filen på hver bærbare datamaskin som skulle bruke konsollen. På en lokasjon med DNS legger du i stedet til oppføringer for de tre navnene.

Klar, eller ikke ennå
Klar, eller ikke ennå
Etter installasjonen inkluderer klargjøringslisten en test for utgående trafikk, slik at en operatør kan vise at ingenting har forsøkt å forlate serveren den siste timen.

Etter installasjonen

Installasjonen er uregistrert (unclaimed). Ingen kan logge inn før noen gjør krav på den i en nettleser ved å sammenligne installasjonens fingeravtrykk med det serveren viser. Kapittel 2.12, Første kjøring, dekker overtakelsen, den første administratoren og passnøkkelen (passkey). Den første administratoren bør være personen hvis e-postadresse ligger i startkonfigurasjonen (seed).

Nodens egen kubeconfig ligger på /etc/rancher/k3s/k3s.yaml, og kan kun leses av root. For å arbeide på klyngen fra en arbeidsstasjon skriver nexusctl kubeconfig den ut, slik kapittel 2.8, Installasjoner på én maskin, beskriver.

Oppdateringer kommer på samme måte som installasjonen gjorde: en utgivelse på signerte medier, kontrollert mot nøkkelen som allerede er installert på serveren, og aldri mot en nøkkel disken har med seg. Kapittel 2.10, Frakoblet installasjon (air-gapped), beskriver den kontrollen.

Gjør krav på denne installasjonen
Gjør krav på denne installasjonen
Siden for å gjøre krav på installasjonen som følger etter installasjonen. Fingeravtrykket vises i åtte grupper på fire, for å sammenlignes med serverens konsoll linje for linje.

Hvis dette feiler

Enhver feil skriver ut nexus-install: FAILED <step>: <what is missing> på konsollen og skriver det samme til /var/lib/nexus/install.state. Rett opp årsaken og kjør installasjonen på nytt fra det første trinnet som ikke er utført:

sudo nexus-install retry
Melding Hva det betyr Hva du skal gjøre
FAILED preflight: payload is for arm64, this machine is amd64 Du startet opp diskbildet for den andre arkitekturen. Bruk diskbildet for denne maskinens arkitektur.
FAILED preflight: memory 11 GiB, need >= 16 GiB Maskinen har mindre enn minimumskravet. Legg til minne, eller gi den virtuelle maskinen mer.
FAILED preflight: free disk 38 GB on /, need >= 50 GB Rotfilsystemet er for lite. Installer på en større disk.
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed Maskinvareklokken ligger etter datoen da installasjonsprogrammet ble bygget. Still klokken i fastvaren (firmware), eller oppgi time i seed.yaml, og prøv på nytt.
FAILED payload: SHA256SUMS signature does not verify Installasjonsprogrammets egne filer er ikke det Adverant signerte. Stopp. Last ned diskbildet på nytt og kontroller det før skriving.
FAILED seed: the installation domain and the first administrator e-mail are required Verken startkonfigurasjonen (seed) eller konsollen oppga dem. Legg dem til i seed.yaml eller svar på spørsmålene.
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) Pakken er Enterprise og startkonfigurasjonen (seed) har ingen lisens. Legg licence.json på seed-volumet.
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h Ingen pakke ble koblet til i tide. Koble til minnepinnen med pakken og prøv på nytt.
FAILED bundle: the bundle does not verify with this installer's release key Pakkekontrollen endte ikke med VERIFY-BUNDLE PASS. Dens egen utskrift, over meldingen, navngir trinnet. Stopp. Ikke bruk den pakken. Skaff en ny.
FAILED bundle: the seed asks for enterprise, the bundle is community Startkonfigurasjonen (seed) og pakken stemmer ikke overens. Rett opp edition i startkonfigurasjonen eller ta med riktig pakke.
FAILED k3s: node not Ready within 10 min k3s startet ikke opp. Sjekk journalen for k3s, og prøv deretter på nytt.
FAILED nexus: helm install nexus Chartet ble ikke installert innen tidsavbruddet. Se på kubectl -n nexus get pods,jobs, øk timeout i startkonfigurasjonen hvis maskinen er treg, og prøv på nytt.
FAILED acceptance: pods not ready Noen poder kjører ikke etter installasjonen. Meldingen navngir opptil fem. Les hendelsene deres, rett opp og prøv på nytt.
FAILED acceptance: jobs not complete: <jobs> En hook-Job er ikke fullført. Les loggen til den navngitte jobben med kubectl -n nexus logs job/<name>, rett opp det den rapporterer, og prøv på nytt.

Før operativsystemet skrives, kan diskvalget også stoppe installasjonen. Meldingen starter med nexus select-disk: REFUSED:. Den vanligste er found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Navngi disken i startkonfigurasjonen (seed) og start opp på nytt.

En mislykket pakkekontroll er den man må ta på alvor. Det betyr at filene på disken ikke er filene Adverant signerte, eller at en fil er lagt til. Installasjonsprogrammet har ikke importert noe på det tidspunktet, så serveren er uendret. Ta vare på disken for sikkerhetsteamet ditt.