Configuration

Configuration#

Un seul fichier, /etc/two/agent.yml, partagé par les quatre binaires : agent -config, metadata -conf, db -conf et dhcp -conf. Le fichier de référence commenté est conf/agent/config.exemple.yml dans le dépôt.

Le chargement se fait par viper : les clés sont celles ci-dessous, en YAML.

Avertissement

Un fichier absent est toléré : toutes les valeurs par défaut s’appliquent. Un fichier présent mais invalide fait en revanche échouer le démarrage, volontairement — jusqu’à la version 0.1.0 il était ignoré en silence, et l’agent tournait alors entièrement sur les défauts sans le dire. Une tabulation d’indentation ou un -- égaré suffisent.

Danger

L’API de l’agent n’a aucune authentification. L’exemple livré écoute sur 0.0.0.0:8080 : quiconque atteint ce port peut créer et détruire des VM et des réseaux sur l’host KVM, c’est-à-dire en prendre le contrôle.

Sur tout déploiement réel : restreindre api.address à une adresse d’administration, ou filtrer le port en amont (pare-feu, réseau dédié). Traiter l’ouverture de ce port comme une décision d’architecture, pas comme un réglage.

Base de données#

database:
  path: "/var/lib/two/data/"

Répertoire de la base clé-valeur Badger. Un seul processus l’ouvre : l’agent. Ni le serveur de metadata ni aucun autre outil ne doit être configuré pour ouvrir le même répertoire pendant que l’agent tourne.

Serveurs#

api:
  address: "0.0.0.0"
  port: 8080

prometheus:
  address: "0.0.0.0"
  port: 9090

admin:
  enabled: false
  address: "127.0.0.1"
  port: 9091

admin expose une inspection en lecture seule de la base (/db?prefix=…). Elle est désactivée par défaut et prévue pour la boucle locale uniquement.

Avertissement

Le contenu de la base inclut vm/<name>/password, qui est un hash de mot de passe. L’activation de l’API d’administration rend ces valeurs lisibles par tout ce qui atteint le port. Ne pas l’exposer hors de la boucle locale.

Exécution des commandes#

worker:
  count: 4
  buffer_size: 100

dispatcher:
  timeout_seconds: 300
  poll_seconds: 2

worker.count est le nombre de goroutines qui exécutent les commandes ; buffer_size le nombre de commandes en attente au-delà duquel Dispatch bloque.

dispatcher.timeout_seconds borne les opérations qui attendent une transition d’état, dont l’extinction d’une VM.

Avertissement

À l’expiration de ce délai, une VM qui ne s’est pas éteinte reçoit un quit QMP — un arrêt brutal. Pour des charges dont l’extinction est lente (bases de données, construction d’images), une valeur confortable évite un système de fichiers invité incohérent.

Correspondance des interfaces#

default_interface: br-000000

interfaces:
  vms: br-000000
  internet: br-000000
  admin: br-000000

Traduit les clés logiques iface_type de l’API vers les bridges physiques de l’host. Une clé inconnue ou omise retombe silencieusement sur default_interface — ce n’est pas une erreur, mais c’est une source de subnets branchés au mauvais endroit sans le dire.

Metadata et QEMU#

metadata:
  run_dir: "/run/two/metadata"

qemu:
  ovmf_code_path: "/usr/share/OVMF/OVMF_CODE.fd"
  ovmf_vars_template: "/usr/share/OVMF/OVMF_VARS.fd"
  uefi_vars_dir: "/run/two/vms/efi"
  serial_dir: "/run/two/vms/serial"
  monitor_dir: "/run/two/vms/monitor"
  qmp_dir: "/run/two/vms/qmp"

Les chemins OVMF sont nécessaires aux VM démarrées avec uefi: true (paquet ovmf sur Debian et Ubuntu). uefi_vars_dir reçoit une copie inscriptible des variables UEFI par VM, créée au démarrage et supprimée à l’arrêt.

Backend DHCP#

dhcp:
  backend: dnsmasq   # ou two

Choisit qui sert le DHCP des subnets créés par cet agent :

Valeur

Serveur

Unit

dnsmasq

dnsmasq, configuré par fichiers dans /etc/dnsmasq.d

dnsmasq@<netns>_<bridge>

two

le binaire dhcp, piloté par socket Unix

dhcp@<netns>_<bridge>

Le défaut est dnsmasq : un fichier de configuration de la 0.1.0, non modifié, se comporte exactement comme avant. Toute autre valeur que dnsmasq ou two fait échouer le démarrage.

Le répertoire d’exécution du backend two — /run/two/dhcp — n’est pas configurable : le script d’enrobage le code en dur, une clé que lui ignorerait serait un mensonge.

Ce que le backend two apporte : la configuration DHCP devient modifiable par VM et non plus seulement par subnet, ce qui permet de n’annoncer la route par défaut que sur une interface d’une VM multi-réseaux. Le watchdog peut en outre interroger le serveur et comparer ce qu’il sert à ce que la base dit — voir Diagnostic.

Bascule d’un backend à l’autre#

Avertissement

L’option ne décide que du backend des nouveaux subnets. Elle ne migre rien : un subnet déjà créé continue d’être servi par le serveur qui l’a été. Changer la valeur sans vider l’hyperviseur laisse l’agent parler à un serveur qui ne tourne pas — les VM existantes continuent, les nouvelles n’obtiennent pas d’adresse.

La bascule est manuelle et suppose un hyperviseur vide :

  1. Supprimer toutes les VM, puis tous les subnets, puis les VPC.

  2. Vérifier qu’il ne reste aucune unit DHCP active et aucun résidu :

    systemctl list-units 'dnsmasq@*' 'dhcp@*'
ls /etc/dnsmasq.d/ /run/two/dhcp/

  3. Modifier dhcp.backend dans /etc/two/agent.yml.

  4. systemctl restart agent — la valeur est lue au démarrage, pas à chaque commande.

  5. Recréer VPC, subnets et VM.

  6. Sur la première VM, vérifier l’adresse et les trois routes : la route par défaut, la route vers le CIDR du VPC, et la route /32 vers 169.254.169.254. C’est cette dernière qui conditionne le provisionnement cloud-init.

Le retour arrière suit la même procédure. Il n’y a pas de bascule à chaud, dans un sens ni dans l’autre.

Watchdog#

watchdog:
  enabled: true
  interval_seconds: 60

Vérification périodique en lecture seule — voir Observabilité.

Journalisation#

logger:
  level: info   # debug, info, warn, error
  debug: false  # force le niveau debug quel que soit level