Versione 1.0.0-alpha.1ultima
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

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.
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.
- 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 SHA256SUMSVerified OK
- 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 -.
- 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.
- Preflight. L'architettura, l'orologio, la memoria e lo spazio libero su disco, come nella tabella soprastante.
- 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.
- Seed. Legge
seed.yamle richiede sulla console tutto ciò che manca. - Bundle. Trova il volume etichettato
NEXUS-BUNDLEe lo monta in sola lettura. Se non ne è presente alcuno, mostrawaiting-for-bundlee attende fino a un'ora affinché Lei lo colleghi. Quindi esegue il controllo completo del bundle, che termina conVERIFY-BUNDLE PASS, utilizzando la chiave di rilascio che contiene, prima che qualsiasi elemento venga importato. Un bundle Enterprise richiedelicence.jsonsul seed, e l'edizione del seed deve corrispondere a quella del bundle. - 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.
- 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.
- cert-manager, poi Nexus. Installa cert-manager v1.21.3, poi il chart di Nexus dal bundle, entrambi entro il
timeoutdel seed. - Acceptance. Controlla che ogni pod sia nello stato Running e che ogni Job di tipo hook sia stato completato.
- Credential. Assegna all'utente del sistema operativo
nexusuna nuova password casuale, la mostra una sola volta sulla console e la scrive innexus-os-password.txtsul 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.
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.
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.
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.

