AccediPrenota un briefing

Capitolo 2.9

L'immagine disco dell'installer

Avviate un server bare-metal o una macchina virtuale dall'immagine dell'installer di Nexus per installare il sistema operativo, k3s, cert-manager e Nexus senza rete, verificando ogni file prima dell'uso.

Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

17 minuti di lettura

L'ufficio della capitaneria di porto sulla banchina est di Harrow ha un solo server, nessuna connessione a Internet e nessuno in sede che gestisca Kubernetes. Tomás Reilly aveva comunque bisogno di installarvi Nexus. Ha scritto l'immagine su una chiavetta USB (Universal Serial Bus), vi ha affiancato una seconda chiavetta più piccola con quattro righe di impostazioni e ha avviato il server. Un'ora dopo lo schermo mostrava l'indirizzo della console e le tre righe da aggiungere al file hosts. Non ha digitato un solo comando Kubernetes.

Questo è il compito dell'immagine disco dell'installer. Scrive un sistema operativo minimale sul disco del server, poi al primo avvio verifica ogni file che contiene rispetto alla chiave di rilascio di Adverant, installa k3s senza rete, importa ogni immagine, installa cert-manager e Nexus e controlla che ogni pod sia in esecuzione. Ogni passaggio si interrompe indicando un motivo specifico nel momento stesso in cui qualcosa non va. Non esiste alcuna modalità degradata e non vi è alcuna password predefinita da nessuna parte.

Le due immagini

Ogni versione viene fornita in due tipi di immagine, per due architetture di processore, amd64 e arm64.

File Contenuto Chi può scaricarla
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso Solo l'installer: il sistema operativo, k3s v1.33.6+k3s1, cert-manager v1.21.3 e l'installer di primo avvio. Funziona per entrambe le edizioni e non contiene immagini di Nexus. Chiunque, da downloads.adverant.ai
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso Lo stesso installer con il bundle offline di quell'edizione aggiunto come seconda partizione etichettata NEXUS-BUNDLE. Un unico supporto installa tutto. Community: chiunque. Enterprise: solo dal Suo account Adverant

<arch> è amd64 o arm64, e <edition> è community o enterprise.

L'installer cerca esclusivamente un filesystem etichettato NEXUS-BUNDLE. Nell'immagine tutto-in-uno si tratta della partizione presente sull'immagine stessa. Con l'immagine del solo installer, Lei fornisce il bundle su un secondo disco o chiavetta con quell'etichetta, il che è comodo quando installa diverse sedi da un'unica chiavetta dell'installer cambiando solo il bundle. Il capitolo 2.10, Installazione air-gapped, descrive il bundle.

Le immagini Enterprise e i bundle Enterprise non sono mai anonimi. Si scaricano dal Suo account Adverant su https://account.adverant.ai, nella pagina Downloads, accanto alla Sua licenza. Le immagini e i bundle Community sono pubblici.

Due illustrazioni di dischi sono affiancate. Quella a sinistra, "immagine del solo installer", ha una partizione etichettata "installer del sistema operativo, k3s, cert-manager, installer di primo avvio" e accanto ad essa una chiavetta USB separata etichettata "NEXUS-BUNDLE: il bundle offline dell'edizione". Quella a destra, "immagine tutto-in-uno", ha la stessa prima partizione e una seconda partizione sullo stesso disco etichettata "NEXUS-BUNDLE". Sotto entrambe, una piccola chiavetta USB è etichettata "NEXUS-SEED: seed.yaml, e licence.json per Enterprise", con una nota "facoltativo per Community". Delle frecce da tutte e tre le etichette puntano verso il basso verso un unico riquadro, "il primo avvio trova ciascuna parte tramite la sua etichetta".
L'immagine del solo installer e l'immagine tutto-in-uno, e dove il primo avvio trova ciascuna parte.

Da cosa è composta l'immagine

Il sistema operativo è basato su Debian 13 e non è un'immagine ufficiale Debian. Contiene il sistema di base Debian e nient'altro: nessun pacchetto aggiuntivo, nessun ambiente desktop e nessun mirror. k3s include il proprio container runtime e la propria gestione di rete. La catena di avvio (shim, GRUB, il kernel e il ramdisk iniziale) è identica byte per byte a quella distribuita da Debian, pertanto una macchina con Secure Boot attivo la avvia come qualsiasi installer Debian.

Due compilazioni della stessa versione producono immagini identiche, byte per byte, e la versione non viene pubblicata finché ciò non avviene. I pacchetti sorgente Debian per ogni file binario presente sull'immagine sono pubblicati accanto ad essa come nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, nello stesso elenco di checksum.

Verificare il file scaricato prima di scriverlo

La directory delle immagini su downloads.adverant.ai contiene le immagini, un file SHA256SUMS che copre ogni file pubblicato e SHA256SUMS.sigstore.json, la firma apposta su tale elenco con la chiave di rilascio di Adverant. Ottenga separatamente la chiave pubblica di rilascio, la salvi come release.pub e ne verifichi l'impronta digitale come descritto nel capitolo 2.4, Ottenimento e verifica di una versione.

  1. Verifichi la firma sull'elenco dei checksum. Non esiste un registro di trasparenza per le versioni di Nexus, pertanto il flag che ignora la ricerca nel registro è obbligatorio.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. Controlli l'immagine scaricata rispetto all'elenco:
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

Su un Mac, utilizzi shasum -a 256 -c - al posto di sha256sum -c -.

  1. Scriva l'immagine su una chiavetta USB con lo strumento che utilizza abitualmente, oppure la colleghi alla macchina virtuale come disco ottico.

k3s pubblica i checksum per i propri file di rilascio ma nessuna firma; pertanto, i file di k3s all'interno dell'immagine vengono verificati rispetto ai checksum pubblicati da k3s, provenienti dalla stessa origine dei file. Tutto ciò che è stato compilato da Adverant è firmato.

Bundle suddivisi in parti

Un bundle trasportato su una chiavetta separata occupa diversi gigabyte. Alcuni filesystem, tra cui FAT (File Allocation Table), non possono contenere file di 4 GiB o più; pertanto, i file del bundle vengono pubblicati in parti da 2047 MiB che entrano in qualsiasi chiavetta. Riunisca le parti nell'ordine corretto e controlli il file unito rispetto al relativo .sha256 prima di utilizzarlo.

L'hardware necessario

Il primo avvio controlla la macchina prima di toccare qualsiasi cosa e si rifiuta di proseguire se la macchina è sottodimensionata.

Controllo La base minima Quando viene controllato
Architettura Quella propria dell'immagine: un'immagine amd64 su amd64, arm64 su arm64 Primo avvio
Memoria 16 GiB Primo avvio
Disco di destinazione Esattamente un disco vuoto di almeno 64 GB, oppure il disco indicato dal seed Prima che il sistema operativo venga scritto
Spazio libero su / 50 GB dopo l'installazione del sistema operativo Primo avvio
Orologio Non antecedente alla data di compilazione dell'immagine Primo avvio

Questi sono i requisiti minimi, non una raccomandazione. Con i valori predefiniti del chart, i soli volumi di Nexus raggiungono in totale 142 GiB, quindi un disco da 64 GB supera il controllo dell'installer ma si riempie nel giro di pochi giorni. Utilizzi la dotazione adeguata per un nodo singolo: 8 vCPU (virtual central processing units), 32 GiB di memoria e un SSD (solid-state drive) da 250 GB. Quattro vCPU, 16 GiB e 200 GB sono sufficienti per una valutazione.

Il controllo dell'orologio è presente perché il server non ha rete, e quindi nessun servizio di sincronizzazione dell'ora, al momento dell'installazione. I certificati e le firme vengono verificati rispetto all'orologio. Se l'orologio hardware della macchina è indietro rispetto alla data di compilazione dell'immagine, il primo avvio si interrompe e Le chiede di impostarlo. Lo imposti nella configurazione del firmware e riavvii.

Bare metal e macchine virtuali

L'immagine si avvia su firmware UEFI (Unified Extensible Firmware Interface), sia su server fisici sia su macchine virtuali. Installa il boot loader sia sul percorso dei supporti rimovibili sia su quello abituale, in modo che una VM (virtual machine) senza voci di avvio salvate lo trovi comunque dopo il primo riavvio. Assegni a una VM la memoria e il disco indicati nella tabella soprastante, un disco virtuale vuoto e l'immagine come CD.

L'installer sceglie il disco di destinazione secondo una regola rigorosa e non seleziona mai "il primo disco".

  • Ignora il supporto da cui si è avviato.
  • Ignora i dischi rimovibili, a meno che il seed non ne indichi uno.
  • Ignora qualsiasi disco che abbia già una tabella delle partizioni, di qualunque tipo.
  • Ignora i dischi inferiori a 64 GB e lo segnala sulla console.
  • Procede all'installazione solo quando rimane esattamente un disco.

Su un server con due dischi vuoti si interrompe e Le chiede di scegliere. La scelta si effettua indicando il disco nel seed, con wipe: true, che è l'unico modo in cui scriverà mai su un disco che ha già delle partizioni.

Il volume NEXUS-SEED

Il seed è un piccolo volume, solitamente una chiavetta USB, con un filesystem etichettato NEXUS-SEED e un file seed.yaml al livello principale. L'installer lo monta in sola lettura, legge le impostazioni e lo rimonta in scrittura solo alla fine, per lasciarLe la password del sistema operativo.

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
Chiave Cosa imposta Quando manca
domain Il dominio dell'installazione. L'installer ne ricava i tre host: console.<domain>, api.<domain> e auth.<domain>. Richiesto sulla console del server
adminEmail L'indirizzo email della persona che sarà il primo amministratore Richiesto sulla console del server
edition community o enterprise. Se impostato, deve corrispondere all'edizione del bundle. Ricavato dal bundle
timeout Il tempo massimo che possono impiegare cert-manager e l'installazione di Nexus, espresso come durata quale 30m o 1h 30m
time L'ora corrente in UTC, nel formato stampato dal messaggio dell'orologio (2026-11-14T09:00:00Z), per una macchina il cui orologio hardware non può essere impostato o non mantiene l'impostazione. Una macchina offline non ha alcun server orario da interrogare. Viene utilizzato l'orologio hardware
disk Il disco di destinazione, come /dev/<name>, utilizzato solo insieme a wipe: true La regola del disco vuoto descritta sopra
wipe true consente all'installer di cancellare il disco indicato da disk Nessun disco viene mai cancellato

Per Enterprise, inserisca il file di licenza sullo stesso volume come licence.json. Senza di esso il primo avvio si interrompe al passaggio del seed e segnala che la licenza è mancante. Community non richiede alcuna licenza, e per Community l'intero seed è facoltativo: l'installer richiede il dominio e l'email sulla console e prosegue.

L'installer legge ogni riga come key: value all'inizio della riga. Scriva una chiave per riga, al livello principale, senza virgolette e senza indentazione. Un valore tra virgolette viene letto insieme alle sue virgolette.

Al primo avvio l'installer richiede inoltre sulla console il custode del key store: la metà pubblica di una chiave age, age1..., creata sulla macchina del custode stesso con age-keygen -o custodian.key. Il key store sigilla le proprie chiavi di ripristino associandole ad essa. Il capitolo 2.8, Installazioni su macchina singola, spiega il ruolo dei custodi. Il custode conserva la metà privata offline e al sicuro: senza di essa, nessuno può rimuovere i sigilli del key store dopo un riavvio.

Cosa accade, dall'accensione all'indirizzo della console

Fase uno: il sistema operativo

L'immagine si avvia in un installer Debian non presidiato. Non configura alcuna rete, non utilizza alcun mirror e non installa alcun pacchetto oltre al sistema di base. Imposta il fuso orario su UTC (Coordinated Universal Time), disabilita l'accesso root e crea un unico utente, nexus, la cui password è bloccata. Sceglie il disco di destinazione secondo la regola descritta sopra e scrive un disco GPT (globally unique identifier partition table) con una partizione di sistema EFI (Extensible Firmware Interface) e un filesystem root ext4, senza swap.

Al termine copia l'installer di Nexus sul nuovo sistema, verifica ogni file copiato rispetto all'elenco dei checksum dell'immagine e abilita un servizio di primo avvio. Se un qualsiasi file copiato non corrisponde, si interrompe immediatamente. Quindi espelle il supporto e riavvia.

Fase due: il primo avvio

Al primo avvio il servizio nexus-install viene eseguito una sola volta. Ogni passaggio scrive sulla console del server e nel journal, e si registra come completato, in modo che un eventuale nuovo tentativo riparta dal primo passaggio non completato. Il servizio nel suo complesso può rimanere in esecuzione fino a quattro ore prima che systemd lo interrompa, il che lascia margine per un disco lento e un'ora di attesa per la chiavetta del bundle.

  1. Preflight. L'architettura, l'orologio, la memoria e lo spazio libero su disco, come nella tabella soprastante.
  2. Payload. I file propri dell'installer: la firma sul suo elenco dei checksum con la chiave di rilascio che contiene, poi ogni file rispetto a tale elenco.
  3. Seed. Legge seed.yaml e richiede sulla console tutto ciò che manca.
  4. Bundle. Trova il volume etichettato NEXUS-BUNDLE e lo monta in sola lettura. Se non ne è presente alcuno, mostra waiting-for-bundle e attende fino a un'ora affinché Lei lo colleghi. Quindi esegue il controllo completo del bundle, che termina con VERIFY-BUNDLE PASS, utilizzando la chiave di rilascio che contiene, prima che qualsiasi elemento venga importato. Un bundle Enterprise richiede licence.json sul seed, e l'edizione del seed deve corrispondere a quella del bundle.
  5. k3s. Installa k3s v1.33.6+k3s1 dai file propri dell'immagine con i download disattivati e attende fino a dieci minuti affinché il nodo sia nello stato Ready. Quindi rimuove l'archivio delle immagini air-gap di k3s, in modo che le immagini non vengano importate nuovamente a ogni avvio.
  6. Import. Importa ogni immagine verificata dal bundle, e le immagini di cert-manager, nel container store del nodo. Nulla viene mai scaricato da un registro.
  7. cert-manager, poi Nexus. Installa cert-manager v1.21.3, poi il chart di Nexus dal bundle, entrambi entro il timeout del seed.
  8. Acceptance. Controlla che ogni pod sia nello stato Running e che ogni Job di tipo hook sia stato completato.
  9. Credential. Assegna all'utente del sistema operativo nexus una nuova password casuale, la mostra una sola volta sulla console e la scrive in nexus-os-password.txt sul volume del seed quando il volume è scrivibile.

Il controllo del bundle al passaggio 4 è lo stesso script che si esegue manualmente nel capitolo 2.10, Installazione air-gapped, e stampa le stesse righe:

  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>

La riga 3 conta le immagini provviste di una firma valida e di una SBOM (software bill of materials) firmata, ovvero l'elenco di ciò che ciascuna immagine contiene. I conteggi (<n>) dipendono dall'edizione. Ciò che conta è l'ultima riga.

L'installazione scrive i valori nel formato attuale del chart: global.domain e i tre nomi hosts.* dal dominio del seed, e keys.custody.recipients dal custode che Lei ha fornito sulla console. Installa a partire dal chart e dalle immagini propri del bundle, pertanto la versione sul disco è esattamente la versione che è stata verificata.

Una catena orizzontale di nove riquadri: Preflight, Payload, Seed, Bundle, k3s, Import, cert-manager e Nexus, Acceptance, Credential. Sotto ogni riquadro, una breve etichetta rossa mostra cosa lo interrompe: "memoria, disco, orologio, architettura", "firma o checksum", "nessun dominio o email; nessuna licenza per Enterprise", "nessun NEXUS-BUNDLE in 1 h; VERIFY-BUNDLE FAIL", "nodo non Ready in 10 min", "un'immagine non viene importata", "helm install fallisce entro il timeout", "un pod non in esecuzione, un Job non completato", e nulla sotto Credential. Una freccia di ritorno da ogni riquadro all'inizio della catena è etichettata "nexus-install retry riprende dal primo passaggio non completato".
Il primo avvio dell'immagine dell'installer, un passaggio dopo l'altro, ciascuno in grado di interrompere l'installazione.

Le ultime righe sulla console

Quando ogni passaggio è stato superato, la console mostra una sola volta la password del sistema operativo e l'indirizzo da aprire:

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)

Annoti la password o la prelevi dalla chiavetta del seed, quindi effettui l'accesso come nexus e la modifichi con passwd. Nessuno, inclusa Adverant, conosce una password predefinita per questa macchina, perché non ne esiste una.

L'indirizzo nella riga hosts è quello proprio del server. Senza DNS (Domain Name System) sulla banchina, Tomás ha aggiunto quell'unica riga al file hosts di ciascun laptop che avrebbe utilizzato la console. In una sede dotata di DNS, aggiunga invece i record per i tre nomi.

Pronto, o non ancora
Pronto, o non ancora
Dopo l'installazione, l'elenco di prontezza include un test del traffico in uscita, affinché un operatore possa dimostrare che nulla ha tentato di uscire nell'ultima ora.

Dopo l'installazione

L'installazione non è rivendicata. Nessuno può accedere finché qualcuno non la rivendica in un browser, confrontando l'impronta digitale dell'installazione con quella mostrata dal server. Il capitolo 2.12, Il primo avvio operativo, tratta la rivendicazione, il primo amministratore e la passkey. Il primo amministratore dovrebbe essere la persona la cui email si trova nel seed.

Il kubeconfig proprio del nodo si trova in /etc/rancher/k3s/k3s.yaml, leggibile solo da root. Per lavorare sul cluster da una workstation, nexusctl kubeconfig lo stampa, come descritto nel capitolo 2.8, Installazioni su macchina singola.

Gli aggiornamenti arrivano nello stesso modo dell'installazione: una versione su supporto firmato, verificata rispetto alla chiave già installata sul server e mai rispetto a una chiave portata con sé dal disco. Il capitolo 2.10, Installazione air-gapped, descrive tale controllo.

Riscatta questa installazione
Riscatta questa installazione
La pagina di rivendicazione che segue l'installazione. L'impronta digitale è mostrata in otto gruppi da quattro, da confrontare riga per riga con la console del server.

Se l'operazione fallisce

Ogni errore stampa nexus-install: FAILED <step>: <what is missing> sulla console e scrive lo stesso contenuto in /var/lib/nexus/install.state. Risolva la causa ed esegua nuovamente l'installazione a partire dal primo passaggio non completato:

sudo nexus-install retry
Messaggio Cosa significa Cosa fare
FAILED preflight: payload is for arm64, this machine is amd64 Ha avviato l'immagine dell'altra architettura. Utilizzi l'immagine per l'architettura di questa macchina.
FAILED preflight: memory 11 GiB, need >= 16 GiB La macchina ha risorse inferiori al requisito minimo. Aggiunga memoria, oppure ne assegni di più alla VM.
FAILED preflight: free disk 38 GB on /, need >= 50 GB Il filesystem root è troppo piccolo. Installi su un disco più grande.
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed L'orologio hardware è indietro rispetto alla data in cui è stato compilato l'installer. Imposti l'orologio nel firmware, oppure indichi time in seed.yaml, e riprovi.
FAILED payload: SHA256SUMS signature does not verify I file propri dell'installer non corrispondono a quelli firmati da Adverant. Si fermi. Scarichi nuovamente l'immagine e la verifichi prima di scriverla.
FAILED seed: the installation domain and the first administrator e-mail are required Né il seed né la console li hanno forniti. Li aggiunga a seed.yaml oppure risponda alle richieste a schermo.
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) Il bundle è Enterprise e il seed non ha alcuna licenza. Inserisca licence.json sul volume del seed.
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h Nessun bundle è stato collegato in tempo. Colleghi la chiavetta del bundle e riprovi.
FAILED bundle: the bundle does not verify with this installer's release key Il controllo del bundle non è terminato con VERIFY-BUNDLE PASS. Il relativo output, sopra il messaggio, indica il passaggio interessato. Si fermi. Non utilizzi quel bundle. Se ne procuri uno nuovo.
FAILED bundle: the seed asks for enterprise, the bundle is community Il seed e il bundle non concordano. Corregga edition nel seed oppure utilizzi il bundle corretto.
FAILED k3s: node not Ready within 10 min k3s non si è avviato. Controlli il journal per k3s, quindi riprovi.
FAILED nexus: helm install nexus Il chart non si è installato entro il timeout. Esamini kubectl -n nexus get pods,jobs, aumenti timeout nel seed se la macchina è lenta e riprovi.
FAILED acceptance: pods not ready Alcuni pod non sono in esecuzione dopo l'installazione. Il messaggio ne elenca fino a cinque. Legga i relativi eventi, risolva il problema e riprovi.
FAILED acceptance: jobs not complete: <jobs> Un Job di tipo hook non è terminato. Legga il log del Job indicato con kubectl -n nexus logs job/<name>, risolva quanto segnalato e riprovi.

Prima che il sistema operativo venga scritto, anche la scelta del disco può interrompere l'installazione. Il relativo messaggio inizia con nexus select-disk: REFUSED:. Quello più comune è found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Indichi il disco nel seed e riavvii.

Il mancato superamento del controllo del bundle è l'errore da prendere con la massima serietà. Significa che i file sul disco non sono quelli firmati da Adverant, oppure che è stato aggiunto un file. A quel punto l'installer non ha importato nulla, pertanto il server è intatto. Conservi il disco per il Suo team di sicurezza.