ConnexionPlanifier un briefing

Chapitre 2.9

L'image disque de l'installateur

Démarrez un serveur nu ou une machine virtuelle à partir de l'image d'installation de Nexus : elle installe le système d'exploitation, k3s, cert-manager et Nexus sans réseau, en vérifiant chaque fichier avant son utilisation.

Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

17 minutes de lecture

La capitainerie du quai est de Harrow dispose d'un seul serveur, d'aucune connexion à Internet et de personne sur place qui administre Kubernetes. Tomás Reilly devait pourtant y installer Nexus. Il a écrit l'image sur une clé USB (Universal Serial Bus), a inséré à côté une seconde petite clé contenant quatre lignes de paramètres, et a démarré le serveur. Une heure plus tard, l'écran affichait l'adresse de la console et les trois lignes à ajouter au fichier hosts. Il n'a pas saisi une seule commande Kubernetes.

C'est le rôle de l'image disque de l'installateur. Elle écrit un système d'exploitation minimal sur le disque du serveur, puis, au premier démarrage, vérifie chaque fichier qu'elle contient à l'aide de la clé de publication d'Adverant, installe k3s sans réseau, importe chaque image, installe cert-manager et Nexus, et s'assure que chaque pod est en cours d'exécution. Chaque étape s'arrête avec un motif explicite dès qu'une anomalie survient. Il n'existe aucun mode dégradé ni aucun mot de passe par défaut, où que ce soit.

Les deux images

Chaque version est proposée sous deux types d'images, pour deux architectures de processeur : amd64 et arm64.

Fichier Contenu Qui peut la télécharger
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso L'installateur seul : le système d'exploitation, k3s v1.33.6+k3s1, cert-manager v1.21.3 et l'installateur de premier démarrage. Il fonctionne pour les deux éditions et ne contient aucune image Nexus. Tout le monde, depuis downloads.adverant.ai
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso Le même installateur avec l'archive hors ligne de cette édition ajoutée sous forme de seconde partition étiquetée NEXUS-BUNDLE. Un seul support suffit pour tout installer. Community : tout le monde. Enterprise : uniquement depuis votre compte Adverant

<arch> correspond à amd64 ou arm64, et <edition> à community ou enterprise.

L'installateur recherche exclusivement un système de fichiers étiqueté NEXUS-BUNDLE. Dans l'image tout-en-un, il s'agit de la partition présente sur l'image elle-même. Avec l'image de l'installateur seul, vous apportez l'archive sur un second disque ou une seconde clé portant cette étiquette, ce qui est pratique lorsque vous installez plusieurs sites à partir d'une seule clé d'installation et que vous ne changez que l'archive. Le chapitre 2.10, Installation en environnement isolé, décrit l'archive.

Les images Enterprise et les archives Enterprise ne sont jamais anonymes. Vous les téléchargez depuis votre compte Adverant à l'adresse https://account.adverant.ai, sur la page des téléchargements, à côté de votre licence. Les images et les archives Community sont publiques.

Deux schémas de disques sont placés côte à côte. Celui de gauche, « image de l'installateur seul », comporte une partition étiquetée « installateur du système d'exploitation, k3s, cert-manager, installateur de premier démarrage » et, à côté, une clé USB distincte étiquetée « NEXUS-BUNDLE : l'archive hors ligne de l'édition ». Celui de droite, « image tout-en-un », comporte la même première partition ainsi qu'une seconde partition sur le même disque étiquetée « NEXUS-BUNDLE ». Sous les deux schémas, une petite clé USB est étiquetée « NEXUS-SEED : seed.yaml, et licence.json pour Enterprise », avec une mention « facultatif pour Community ». Des flèches partant des trois étiquettes pointent vers un même encadré : « le premier démarrage trouve chaque élément grâce à son étiquette ».
L'image de l'installateur seul et l'image tout-en-un, et l'endroit où le premier démarrage trouve chaque élément.

De quoi l'image est construite

Le système d'exploitation repose sur Debian 13 et n'est pas une image officielle Debian. Il contient le système de base Debian et rien d'autre : aucun paquet supplémentaire, aucun environnement de bureau et aucun miroir. k3s fournit son propre moteur d'exécution de conteneurs et sa propre gestion du réseau. La chaîne d'amorçage (shim, GRUB, le noyau et le disque mémoire initial) est, octet par octet, celle que distribue Debian ; ainsi, une machine dotée de Secure Boot activé la démarre comme n'importe quel installateur Debian.

Deux compilations d'une même version produisent des images identiques, octet par octet, et la version n'est pas publiée tant que ce n'est pas le cas. Les paquets sources Debian correspondant à chaque binaire présent sur l'image sont publiés à côté de celle-ci sous le nom nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, dans la même liste de sommes de contrôle.

Vérifier le téléchargement avant de l'écrire

Le répertoire d'images sur downloads.adverant.ai contient les images, un fichier SHA256SUMS couvrant chaque fichier publié, et SHA256SUMS.sigstore.json, la signature de cette liste générée avec la clé de publication d'Adverant. Récupérez la clé publique de publication séparément, enregistrez-la sous le nom release.pub, et vérifiez son empreinte comme le décrit le chapitre 2.4, Obtenir et vérifier une version.

  1. Vérifiez la signature de la liste de sommes de contrôle. Il n'existe pas de journal de transparence pour les versions de Nexus ; l'option qui ignore la consultation du journal est donc requise.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. Vérifiez l'image que vous avez téléchargée à l'aide de la liste :
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

Sur un Mac, utilisez shasum -a 256 -c - au lieu de sha256sum -c -.

  1. Écrivez l'image sur une clé USB à l'aide de votre outil habituel, ou montez-la sur la machine virtuelle comme disque optique.

k3s publie des sommes de contrôle pour ses fichiers de version mais aucune signature ; les fichiers k3s contenus dans l'image sont donc vérifiés par rapport aux sommes de contrôle publiées par k3s, provenant de la même source que les fichiers. Tout ce qu'Adverant a compilé est signé.

Archives découpées

Une archive que vous transportez sur une clé distincte pèse plusieurs gigaoctets. Certains systèmes de fichiers, notamment FAT (File Allocation Table), ne peuvent pas contenir un fichier de 4 GiB ou plus ; les fichiers d'archive sont donc publiés en segments de 2047 MiB qui tiennent sur n'importe quelle clé. Réassemblez les segments dans l'ordre et vérifiez le fichier reconstitué à l'aide de son fichier .sha256 avant de l'utiliser.

Le matériel requis

Le premier démarrage vérifie la machine avant de modifier quoi que ce soit, et refuse de poursuivre si elle est sous-dimensionnée.

Vérification Le socle Moment de la vérification
Architecture Celle de l'image : une image amd64 sur amd64, arm64 sur arm64 Premier démarrage
Mémoire 16 GiB Premier démarrage
Disque cible Exactement un disque vide d'au moins 64 GB, ou le disque désigné par le volume d'amorçage Avant l'écriture du système d'exploitation
Espace libre sur / 50 GB une fois le système d'exploitation installé Premier démarrage
Horloge Pas antérieure à la date de construction de l'image Premier démarrage

Il s'agit de seuils minimaux, et non d'une recommandation. Avec les valeurs par défaut du chart, les volumes de Nexus totalisent à eux seuls 142 GiB ; un disque de 64 GB passe donc l'étape de l'installateur mais se remplit en quelques jours. Prévoyez ce dont un nœud unique a besoin : 8 vCPU (virtual central processing units), 32 GiB de mémoire et un SSD (solid-state drive) de 250 GB. Quatre vCPU, 16 GiB et 200 GB suffisent pour une évaluation.

La vérification de l'horloge est nécessaire car le serveur n'a pas de réseau, et donc pas de service de synchronisation horaire, lors de l'installation. Les certificats et les signatures sont vérifiés par rapport à l'horloge. Si l'horloge matérielle de la machine retarde par rapport à la date de construction de l'image, le premier démarrage s'arrête et vous invite à la régler. Réglez-la dans l'interface du micrologiciel et redémarrez.

Serveurs physiques et machines virtuelles

L'image démarre sur un micrologiciel UEFI (Unified Extensible Firmware Interface), aussi bien sur des serveurs physiques que sur des machines virtuelles. Elle installe le chargeur d'amorçage sur le chemin des supports amovibles ainsi que sur le chemin habituel, de sorte qu'une VM (virtual machine) sans entrée d'amorçage enregistrée le trouve tout de même après le premier redémarrage. Attribuez à la VM la mémoire et l'espace disque indiqués dans le tableau ci-dessus, un disque virtuel vide, et l'image sous forme de CD.

L'installateur sélectionne le disque cible selon une règle stricte et ne choisit jamais « le premier disque ».

  • Il ignore le support à partir duquel il a démarré.
  • Il ignore les disques amovibles, sauf si le volume d'amorçage en désigne un.
  • Il ignore tout disque possédant déjà une table de partitions, quel qu'en soit le type.
  • Il ignore les disques de moins de 64 GB et l'indique sur la console.
  • Il ne procède à l'installation que lorsqu'il reste exactement un seul disque.

Sur un serveur doté de deux disques vierges, il s'arrête et vous demande de choisir. Vous faites ce choix en désignant le disque dans le volume d'amorçage, avec wipe: true, ce qui constitue d'ailleurs le seul moyen pour qu'il accepte d'écrire sur un disque contenant déjà des partitions.

Le volume NEXUS-SEED

Le volume d'amorçage (seed) est un petit volume, généralement une clé USB, doté d'un système de fichiers étiqueté NEXUS-SEED et contenant un fichier seed.yaml à sa racine. L'installateur le monte en lecture seule, lit les paramètres, et ne le remonte en écriture qu'à la toute fin, pour vous y déposer le mot de passe du système d'exploitation.

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
Clé Ce qu'il définit S'il est absent
domain Le domaine de l'installation. L'installateur en déduit les trois hôtes : console.<domain>, api.<domain> et auth.<domain>. Demandé sur la console du serveur
adminEmail L'adresse e-mail de la personne qui sera le premier administrateur Demandé sur la console du serveur
edition community ou enterprise. Lorsqu'elle est définie, cette valeur doit correspondre à l'édition de l'archive. Déduit de l'archive
timeout La durée maximale accordée à l'installation de cert-manager et de Nexus, sous la forme d'une durée telle que 30m ou 1h 30m
time L'heure actuelle en UTC, au format affiché par le message d'horloge (2026-11-14T09:00:00Z), pour une machine dont l'horloge matérielle ne peut pas être réglée ou ne conserve pas son réglage. Une machine hors ligne n'a aucun serveur de temps à interroger. L'horloge matérielle est utilisée
disk Le disque cible, sous la forme /dev/<name>, utilisé uniquement conjointement avec wipe: true La règle du disque vide ci-dessus
wipe true autorise l'installateur à effacer le disque désigné par disk Aucun disque n'est jamais effacé

Pour l'édition Enterprise, placez le fichier de licence sur le même volume sous le nom licence.json. Sans lui, le premier démarrage s'arrête à l'étape du volume d'amorçage et signale l'absence de la licence. L'édition Community ne nécessite aucune licence, et le volume d'amorçage tout entier y est facultatif : l'installateur demande le domaine et l'adresse e-mail sur la console, puis poursuit.

L'installateur lit chaque ligne sous la forme key: value en début de ligne. Écrivez une clé par ligne, à la racine, sans guillemets et sans indentation. Une valeur entre guillemets est lue avec ses guillemets.

Au premier démarrage, l'installateur demande également sur la console le dépositaire du magasin de clés : la partie publique d'une clé age, age1..., générée sur la propre machine du dépositaire avec age-keygen -o custodian.key. Le magasin de clés y scelle ses clés de récupération. Le chapitre 2.8, Installations sur machine unique, explique le rôle des dépositaires. Le dépositaire conserve la partie privée hors ligne et en lieu sûr : sans elle, personne ne peut desceller le magasin de clés après un redémarrage.

Ce qui se passe, de la mise sous tension jusqu'à l'adresse de la console

Première étape : le système d'exploitation

L'image démarre sur un installateur Debian automatisé. Il ne configure aucun réseau, n'utilise aucun miroir et n'installe aucun paquet au-delà du système de base. Il règle le fuseau horaire sur UTC (Coordinated Universal Time), désactive la connexion root et crée un seul utilisateur, nexus, dont le mot de passe est verrouillé. Il sélectionne le disque cible selon la règle ci-dessus et écrit un disque GPT (globally unique identifier partition table) comprenant une partition système EFI (Extensible Firmware Interface) et un système de fichiers racine ext4, sans espace d'échange (swap).

À la fin, il copie l'installateur Nexus sur le nouveau système, vérifie chaque fichier copié par rapport à la liste de sommes de contrôle de l'image, et active un service de premier démarrage. Si l'un des fichiers copiés ne correspond pas, il s'arrête immédiatement. Ensuite, il éjecte le support et redémarre.

Deuxième étape : le premier démarrage

Au premier démarrage, le service nexus-install s'exécute une seule fois. Chaque étape s'affiche sur la console du serveur et dans le journal système, et s'enregistre comme terminée, de sorte qu'une nouvelle tentative reprend à la première étape non achevée. Le service dans son ensemble peut s'exécuter pendant un maximum de quatre heures avant que systemd ne l'arrête, ce qui laisse de la marge pour un disque lent et une heure d'attente pour l'insertion de la clé contenant l'archive.

  1. Vérifications préalables (Preflight). L'architecture, l'horloge, la mémoire et l'espace disque libre, conformément au tableau ci-dessus.
  2. Charge utile (Payload). Les propres fichiers de l'installateur : la signature de sa liste de sommes de contrôle à l'aide de la clé de publication qu'il embarque, puis chaque fichier par rapport à cette liste.
  3. Amorçage (Seed). Lit seed.yaml et demande sur la console tout élément manquant.
  4. Archive (Bundle). Recherche le volume étiqueté NEXUS-BUNDLE et le monte en lecture seule. S'il n'y en a pas, il affiche waiting-for-bundle et attend jusqu'à une heure que vous le connectiez. Il exécute ensuite la vérification complète de l'archive, qui se termine par VERIFY-BUNDLE PASS, à l'aide de la clé de publication qu'il embarque, avant toute importation. Une archive Enterprise requiert licence.json sur le volume d'amorçage, et l'édition indiquée sur ce dernier doit correspondre à celle de l'archive.
  5. k3s. Installe k3s v1.33.6+k3s1 à partir des propres fichiers de l'image avec les téléchargements désactivés, et attend jusqu'à dix minutes que le nœud passe à l'état Ready. Il supprime ensuite l'archive d'images hors ligne de k3s, afin que les images ne soient pas réimportées à chaque démarrage.
  6. Importation (Import). Importe chaque image vérifiée de l'archive, ainsi que les images de cert-manager, dans le magasin de conteneurs du nœud. Rien n'est jamais téléchargé depuis un registre.
  7. cert-manager, puis Nexus. Installe cert-manager v1.21.3, puis le chart Nexus depuis l'archive, tous deux dans le délai timeout défini sur le volume d'amorçage.
  8. Validation (Acceptance). Vérifie que chaque pod est à l'état Running et que chaque Job de hook est terminé.
  9. Identifiants (Credential). Attribue à l'utilisateur système nexus un nouveau mot de passe aléatoire, l'affiche une seule fois sur la console et l'écrit dans nexus-os-password.txt sur le volume d'amorçage lorsque celui-ci est accessible en écriture.

La vérification de l'archive à l'étape 4 correspond au même script que celui que vous exécutez manuellement au chapitre 2.10, Installation en environnement isolé, et affiche les mêmes lignes :

  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 ligne 3 dénombre les images qui portent une signature valide et une SBOM (software bill of materials, ou nomenclature logicielle) signée, c'est-à-dire la liste de ce que contient chaque image. Les totaux (<n>) dépendent de l'édition. Ce qui importe, c'est la dernière ligne.

L'installation écrit les valeurs au format actuel du chart : global.domain et les trois noms hosts.* dérivés du domaine du volume d'amorçage, ainsi que keys.custody.recipients à partir du dépositaire que vous avez renseigné sur la console. Elle procède à l'installation à partir du chart et des images propres à l'archive, de sorte que la version présente sur le disque correspond exactement à la version qui a été vérifiée.

Une chaîne horizontale de neuf encadrés : Preflight, Payload, Seed, Bundle, k3s, Import, cert-manager et Nexus, Acceptance, Credential. Sous chaque encadré, une courte étiquette rouge indique ce qui bloque l'étape : « mémoire, disque, horloge, architecture », « signature ou somme de contrôle », « pas de domaine ou d'e-mail ; pas de licence pour Enterprise », « pas de NEXUS-BUNDLE en 1 h ; VERIFY-BUNDLE FAIL », « nœud non Ready en 10 min », « échec d'importation d'une image », « échec de helm install dans le délai imparti », « un pod non actif, un Job non terminé », et rien sous Credential. Une flèche de retour partant de chaque encadré vers le début de la chaîne porte la mention « nexus-install retry reprend à la première étape non terminée ».
Le premier démarrage de l'image de l'installateur, étape par étape, chacune pouvant interrompre l'installation.

Les dernières lignes sur la console

Lorsque toutes les étapes ont réussi, la console affiche une seule fois le mot de passe du système d'exploitation ainsi que l'adresse à ouvrir :

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)

Notez le mot de passe ou récupérez-le sur la clé d'amorçage, puis connectez-vous en tant que nexus et modifiez-le avec passwd. Personne, pas même Adverant, ne connaît de mot de passe par défaut pour cette machine, car il n'en existe aucun.

L'adresse figurant dans la ligne hosts est celle du serveur lui-même. En l'absence de DNS (Domain Name System) sur le quai, Tomás a ajouté cette unique ligne au fichier hosts de chaque ordinateur portable devant utiliser la console. Sur un site disposant d'un DNS, ajoutez plutôt des enregistrements pour les trois noms.

Prêt, ou pas encore
Prêt, ou pas encore
Après l'installation, la liste de contrôle de disponibilité inclut un test de trafic sortant, permettant à un opérateur de démontrer qu'aucune donnée n'a tenté de sortir au cours de la dernière heure.

Après l'installation

L'installation n'est pas encore revendiquée. Personne ne peut se connecter tant qu'un utilisateur ne l'a pas revendiquée dans un navigateur, en comparant l'empreinte de l'installation avec celle qu'affiche le serveur. Le chapitre 2.12, Le premier lancement, traite de la revendication, du premier administrateur et de la clé d'accès (passkey). Le premier administrateur doit être la personne dont l'adresse e-mail figure dans le volume d'amorçage.

Le propre fichier kubeconfig du nœud se trouve à l'emplacement /etc/rancher/k3s/k3s.yaml, lisible uniquement par root. Pour travailler sur le cluster depuis un poste de travail, la commande nexusctl kubeconfig l'affiche, comme le décrit le chapitre 2.8, Installations sur machine unique.

Les mises à jour s'effectuent de la même manière que l'installation : une version sur un support signé, vérifiée à l'aide de la clé déjà installée sur le serveur et jamais à l'aide d'une clé apportée par le disque lui-même. Le chapitre 2.10, Installation en environnement isolé, décrit cette vérification.

Réclamer cette installation
Réclamer cette installation
La page de revendication qui suit l'installation. L'empreinte est présentée en huit groupes de quatre caractères, afin de pouvoir la comparer ligne par ligne avec la console du serveur.

En cas d'échec

Chaque échec affiche nexus-install: FAILED <step>: <what is missing> sur la console et écrit la même information dans /var/lib/nexus/install.state. Corrigez la cause et relancez l'installation à partir de la première étape non terminée :

sudo nexus-install retry
Message Ce que cela signifie Que faire
FAILED preflight: payload is for arm64, this machine is amd64 Vous avez démarré l'image correspondant à l'autre architecture. Utilisez l'image correspondant à l'architecture de cette machine.
FAILED preflight: memory 11 GiB, need >= 16 GiB La machine dispose de moins de mémoire que le seuil minimal. Ajoutez de la mémoire, ou attribuez-en davantage à la VM.
FAILED preflight: free disk 38 GB on /, need >= 50 GB Le système de fichiers racine est trop petit. Installez le système sur un disque plus grand.
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed L'horloge matérielle retarde par rapport à la date de construction de l'installateur. Réglez l'horloge dans le micrologiciel, ou renseignez time dans seed.yaml, puis réessayez.
FAILED payload: SHA256SUMS signature does not verify Les propres fichiers de l'installateur ne correspondent pas à ce qu'Adverant a signé. Arrêtez tout. Téléchargez à nouveau l'image et vérifiez-la avant de l'écrire.
FAILED seed: the installation domain and the first administrator e-mail are required Ni le volume d'amorçage ni la console ne les ont fournis. Ajoutez-les dans seed.yaml ou répondez aux invites sur la console.
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) L'archive est une édition Enterprise et le volume d'amorçage ne contient pas de licence. Placez licence.json sur le volume d'amorçage.
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h Aucune archive n'a été connectée à temps. Connectez la clé contenant l'archive et réessayez.
FAILED bundle: the bundle does not verify with this installer's release key La vérification de l'archive ne s'est pas terminée par VERIFY-BUNDLE PASS. Sa propre sortie, juste au-dessus du message, indique l'étape concernée. Arrêtez tout. N'utilisez pas cette archive. Procurez-vous-en une nouvelle.
FAILED bundle: the seed asks for enterprise, the bundle is community Le volume d'amorçage et l'archive ne concordent pas. Corrigez edition dans le volume d'amorçage ou apportez la bonne archive.
FAILED k3s: node not Ready within 10 min k3s n'a pas démarré. Consultez le journal système pour k3s, puis réessayez.
FAILED nexus: helm install nexus Le chart ne s'est pas installé dans le délai imparti. Consultez kubectl -n nexus get pods,jobs, augmentez timeout dans le volume d'amorçage si la machine est lente, puis réessayez.
FAILED acceptance: pods not ready Certains pods ne sont pas en cours d'exécution après l'installation. Le message en nomme jusqu'à cinq. Lisez leurs événements, corrigez le problème et réessayez.
FAILED acceptance: jobs not complete: <jobs> Un Job de hook ne s'est pas terminé. Lisez le journal du Job nommé à l'aide de kubectl -n nexus logs job/<name>, corrigez ce qu'il signale, puis réessayez.

Avant l'écriture du système d'exploitation, la sélection du disque peut également arrêter l'installation. Son message commence par nexus select-disk: REFUSED:. Le cas le plus courant est found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Désignez le disque dans le volume d'amorçage et redémarrez.

L'échec de la vérification de l'archive est celui qu'il faut prendre très au sérieux. Cela signifie que les fichiers présents sur le disque ne sont pas ceux qu'Adverant a signés, ou qu'un fichier a été ajouté. À ce stade, l'installateur n'a encore rien importé ; le serveur est donc intact. Conservez le disque pour votre équipe de sécurité.