Installer depuis un dépôt hors ligne

Ce guide installe un contrôleur Kyvernon et un premier hôte sur des serveurs Debian 13 ou Ubuntu 26.04 sans accès à Internet. Tout provient d'un seul répertoire, le dépôt, que vous recevez sur une clé USB, un DVD ou un partage de fichiers. Le guide de la première connexion (Première connexion) continue là où celui-ci se termine.

Avant de commencer

• Deux serveurs Debian ou Ubuntu (ou un seul pour un premier essai) : un pour le contrôleur, un hôte avec la prise en charge de la virtualisation (/dev/kvm présent). L'hôte a besoin des paquets de la distribution qemu-utils, ovmf et swtpm ; un dépôt peut les fournir dans deps/.
• Le répertoire du dépôt kyvernon-<version>/ et, séparément, la clé publique de la version de Kyvernon, que vous obtenez auprès de Kyvernon et non dans le dépôt. L'installateur n'accepte pas la clé provenant du dépôt lui-même (la copie sous keys/ ne sert qu'à la comparaison) : la signature a pour but que le dépôt ne puisse pas se porter garant de lui-même.
• Un accès root sur les deux serveurs.

1. Vérifier le dépôt

Copiez le dépôt sur le serveur, puis vérifiez-le en tant qu'utilisateur normal :

cd kyvernon-0.1.0
./kyvernon-install --verify-only --pubkey /path/to/release-signing.minisign.pub

Le script vérifie la signature de l'index (depot.json), puis la somme de contrôle de chaque fichier, et refuse un répertoire contenant des fichiers que l'index ne liste pas ou des liens symboliques. Lors de l'installation, il remet à dpkg ses propres copies vérifiées des paquets, et non les fichiers du répertoire du dépôt. Il affiche depot ok en cas de succès ; pour toute autre sortie, arrêtez-vous et contactez votre fournisseur. Si vous préférez l'outil standard : minisign -Vm depot.json -p release-signing.minisign.pub vérifie la même signature.

2. Installer le contrôleur

sudo ./kyvernon-install --role controller --pubkey /path/to/release-signing.minisign.pub

Cette commande installe kyvernon-controller et le client en ligne de commande kyvernon-cli. Aucun service n'est encore démarré. Ensuite :

1. Écrivez la configuration à partir du squelette et modifiez-la. Le squelette documente chaque clé ; vérifiez au moins [http] listen, [grpc] listen et [tls] san (les noms que les clients utiliseront) :

   sudo cp /usr/share/kyvernon/controller.toml.example /etc/kyvernon/controller.toml
   sudo chown root:kyvernon /etc/kyvernon/controller.toml
   sudo chmod 0640 /etc/kyvernon/controller.toml
   sudo editor /etc/kyvernon/controller.toml

2. Écrivez le mot de passe initial de l'administrateur (12 à 256 caractères). Il est lu une seule fois au premier démarrage et doit être changé à la première connexion :

   (umask 077; sudo sh -c 'printf "%s\n" "a-long-initial-password" > /etc/kyvernon/admin-password')

3. Vérifiez la configuration et démarrez le service :

   sudo kyvernon-controller --config /etc/kyvernon/controller.toml check-config
   sudo systemctl enable --now kyvernon-controller.service
   sudo systemctl status kyvernon-controller.service

Les paramètres de controller.toml sont listés dans Configuration.

L'installation a créé /etc/kyvernon/join-token (réservé à root). Les hôtes le présentent lorsqu'ils rejoignent le contrôleur ; copiez-le sur chaque hôte à l'étape 3. Le certificat d'amorçage TLS du contrôleur est /var/lib/kyvernon/controller/tls/bootstrap-cert.pem ; les hôtes en ont aussi besoin.

Ouvrez https://<controller>:8443/ dans un navigateur et connectez-vous en tant que admin avec le mot de passe initial (Première connexion, section 1).

3. Installer un hôte

Sur l'hôte :

sudo ./kyvernon-install --role agent --pubkey /path/to/release-signing.minisign.pub

Cette commande installe kyvernon-vmm et kyvernon-agent (ainsi que les paquets de deps/ lorsque le dépôt les contient). Si dpkg signale des paquets manquants tels que ovmf ou swtpm, installez-les depuis le miroir de votre distribution et relancez la commande. Aucun service n'est encore démarré. Ensuite :

1. Copiez depuis le contrôleur le jeton d'adhésion et son certificat d'amorçage :

   sudo install -m 0600 -o root -g root join-token /etc/kyvernon/join-token
   sudo install -m 0644 -o root -g kyvernon bootstrap-cert.pem /etc/kyvernon/controller-ca.pem

2. Écrivez la configuration de l'agent à partir du squelette. Réglez [control_plane] endpoint sur l'adresse gRPC du contrôleur (https://<controller>:8444), server_name sur un nom de la liste [tls] san du contrôleur, et management_address sur l'adresse de cet hôte :

   sudo cp /usr/share/kyvernon/agent.toml.example /etc/kyvernon/agent.toml
   sudo chown root:kyvernon /etc/kyvernon/agent.toml
   sudo chmod 0640 /etc/kyvernon/agent.toml
   sudo editor /etc/kyvernon/agent.toml

3. Démarrez l'agent :

   sudo systemctl enable --now kyvernon-agent.service
   sudo journalctl -u kyvernon-agent.service -f

Le journal montre l'hôte s'enregistrant auprès du contrôleur ; l'hôte apparaît ensuite dans la console web sous Hôtes. Le jeton d'adhésion à usage unique n'est plus nécessaire ensuite : l'hôte a son propre certificat (/var/lib/kyvernon/agent/identity). Vous pouvez vider le fichier du jeton (sudo truncate -s0 /etc/kyvernon/join-token) mais conservez-le : l'unité le charge à chaque démarrage.

Le jeton d'adhésion ne remplace pas l'identité d'un hôte enregistré : un hôte qui a perdu son certificat (réinstallé, ou /var/lib/kyvernon/agent/identity supprimé) est refusé lorsqu'il s'enregistre à nouveau sous le même nom. Libérez-le d'abord, en tant qu'administrateur, par un ajout forcé de l'hôte à son cluster (POST /v1/clusters/{id}/hosts avec "force": true), ou supprimez l'hôte ; l'agent rejoint alors le contrôleur avec le jeton d'adhésion et garde son identifiant d'hôte.