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.

MTU#

network:
  mtu_vm: 1500
  allow_mtu_vm_below_1500: false
  allow_mtu_underlay_below_9000: false
  • mtu_vm — le MTU de toutes les VM, et de tous les bridges, veth, taps et interfaces VXLAN que l’agent crée. Il est annoncé aux VM par l’option DHCP 26 et par host_mtu. Il doit être identique sur tous les hyperviseurs. 1500 au plus ; en dessous, seulement avec allow_mtu_vm_below_1500, et jamais sous 1280. Une valeur hors de ces bornes fait échouer le démarrage de l’agent.

  • allow_mtu_underlay_below_9000 — l’underlay est attendu à exactement 9000. Sans cette option, un subnet vxlan dont l’interface (celle de iface_type, ou default_interface) n’est pas à 9000 est refusé (422), comme un VPC avec l3vni si default_interface ne l’est pas (409). Dans tous les cas, l’underlay doit faire au moins mtu_vm + 50 (en-tête VXLAN).

Un subnet bridge est refusé (422) si son bridge est sous mtu_vm ; il n’y a pas d’encapsulation, donc pas de marge à prévoir. Les interfaces sont créées au MTU en vigueur à la création du subnet : changer mtu_vm ne modifie pas les subnets existants, il faut les recréer.

Plan de contrôle BGP#

bgp:
  asn: 64600
  route_reflectors: [10.255.255.1, 10.255.255.2]

Section facultative. Absente, l’agent ne touche pas à FRR : sa configuration reste à poser à la main, comme avant. Présente, l’agent pilote la configuration BGP de l’hyperviseur : à chaque démarrage, avant d’ouvrir son API, il applique par vtysh la base décrite dans Premier hyperviseur, puis l’enregistre par write memory.

  • asn — l’AS de l’hyperviseur, commun à tous les hyperviseurs du cluster (iBGP vers le route reflector). Obligatoire dès que la section existe.

  • route_reflectors — au moins une adresse IPv4, sans doublon. Un route reflector retiré de la liste est retiré de FRR au démarrage suivant.

Le router-id n’est pas configurable : c’est l’adresse IPv4 primaire de default_interface, celle qui sert de VTEP.

Le démarrage échoue si la section est incomplète, si default_interface n’a pas d’adresse IPv4 primaire, si vtysh refuse une commande, ou si FRR tourne déjà sous un autre AS : changer d”asn suppose de retirer l’ancienne instance à la main.

Avertissement

/etc/frr/frr.conf devient un fichier généré : write memory le réécrit à partir de la configuration en mémoire de FRR. Une modification faite dans le fichier sans être rechargée est perdue au prochain démarrage de l’agent.

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/uefi"
  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: two   # ou dnsmasq

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 two. Un hyperviseur mis à jour depuis la 0.1.0 avec des subnets existants doit déclarer backend: dnsmasq avant la mise à jour, ou être vidé puis basculé (voir plus bas) : ses subnets restent servis par dnsmasq. 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é. Désactivée par défaut (enabled: false) : sans cette section, aucun contrôle ne tourne.

Journalisation#

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