Installeren vanuit een offline depot

Deze handleiding installeert een Kyvernon-controller en een eerste host op Debian 13- of Ubuntu 26.04-servers zonder internettoegang. Alles komt uit één map, het depot, dat u ontvangt op een USB-stick, een dvd of een bestandsshare. De handleiding voor de eerste aanmelding (Eerste aanmelding) gaat verder waar deze eindigt.

Voordat u begint

• Twee Debian- of Ubuntu-servers (of één voor een eerste proef): een voor de controller, een host met ondersteuning voor virtualisatie (/dev/kvm aanwezig). De host heeft de distributiepakketten qemu-utils, ovmf en swtpm nodig; een depot kan ze meeleveren in deps/.
• De depotmap kyvernon-<version>/ en, afzonderlijk, de publieke sleutel van de release van Kyvernon, die u van Kyvernon krijgt en niet uit het depot. Het installatieprogramma accepteert de sleutel uit het depot zelf niet (de kopie onder keys/ staat er alleen ter vergelijking): het doel van de handtekening is dat het depot niet voor zichzelf kan instaan.
• Rootrechten op beide servers.

1. Het depot verifiëren

Kopieer het depot naar de server en verifieer het daarna als gewone gebruiker:

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

Het script controleert de handtekening over de index (depot.json) en daarna het controlegetal van elk bestand, en weigert een map met bestanden die de index niet vermeldt of met symbolische koppelingen. Bij de installatie geeft het dpkg zijn eigen geverifieerde kopieën van de pakketten, niet de bestanden in de depotmap. Het toont depot ok bij succes; stop bij elke andere uitvoer en neem contact op met uw leverancier. Als u liever het standaardprogramma gebruikt: minisign -Vm depot.json -p release-signing.minisign.pub verifieert dezelfde handtekening.

2. De controller installeren

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

Dit installeert kyvernon-controller en de opdrachtregelclient kyvernon-cli. Er wordt nog geen service gestart. Daarna:

1. Schrijf de configuratie vanuit het skelet en pas haar aan. Het skelet documenteert elke sleutel; controleer minstens [http] listen, [grpc] listen en [tls] san (de namen die clients gaan gebruiken):

   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. Schrijf het initiële beheerderswachtwoord (12 tot 256 tekens). Het wordt eenmalig gelezen bij de eerste start en moet bij de eerste aanmelding worden gewijzigd:

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

3. Controleer de configuratie en start de service:

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

De instellingen van controller.toml staan in Configuratie.

De installatie heeft /etc/kyvernon/join-token aangemaakt (alleen voor root). Hosts tonen het wanneer ze zich aansluiten; kopieer het in stap 3 naar elke host. Het TLS-opstartcertificaat van de controller is /var/lib/kyvernon/controller/tls/bootstrap-cert.pem; hosts hebben dat ook nodig.

Open https://<controller>:8443/ in een browser en meld u aan als admin met het initiële wachtwoord (Eerste aanmelding, sectie 1).

3. Een host installeren

Op de hostserver:

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

Dit installeert kyvernon-vmm en kyvernon-agent (en de pakketten in deps/ als het depot ze meelevert). Als dpkg ontbrekende pakketten meldt, zoals ovmf of swtpm, installeer ze dan vanaf uw distributiemirror en voer de opdracht opnieuw uit. Er wordt nog geen service gestart. Daarna:

1. Kopieer het join-token en het opstartcertificaat vanaf de controller:

   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. Schrijf de agentconfiguratie vanuit het skelet. Stel [control_plane] endpoint in op het gRPC-adres van de controller (https://<controller>:8444), server_name op een naam uit de lijst [tls] san van de controller en management_address op het adres van deze host:

   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. Start de agent:

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

Het journaal toont hoe de host zich bij de controller registreert; de host verschijnt daarna in de webconsole onder Hosts. Het eenmalige join-token is daarna niet meer nodig: de host heeft een eigen certificaat (/var/lib/kyvernon/agent/identity). U mag het tokenbestand leegmaken (sudo truncate -s0 /etc/kyvernon/join-token) maar bewaar het: de unit laadt het bij elke start.

Het join-token vervangt de identiteit van een geregistreerde host niet: een host die zijn certificaat kwijt is (opnieuw geïnstalleerd, of /var/lib/kyvernon/agent/identity verwijderd) wordt geweigerd wanneer hij zich opnieuw onder dezelfde naam registreert. Geef hem eerst vrij, als beheerder, met een geforceerde toevoeging van de host aan zijn cluster (POST /v1/clusters/{id}/hosts met "force": true), of verwijder de host; daarna sluit de agent zich weer aan met het join-token en behoudt hij zijn host-id.