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 parhost_mtu. Il doit être identique sur tous les hyperviseurs. 1500 au plus ; en dessous, seulement avecallow_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 subnetvxlandont l’interface (celle deiface_type, oudefault_interface) n’est pas à 9000 est refusé (422), comme un VPC avecl3vnisidefault_interfacene l’est pas (409). Dans tous les cas, l’underlay doit faire au moinsmtu_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, configuré par fichiers dans |
|
|
le binaire |
|
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 :
Supprimer toutes les VM, puis tous les subnets, puis les VPC.
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/
Modifier
dhcp.backenddans/etc/two/agent.yml.systemctl restart agent— la valeur est lue au démarrage, pas à chaque commande.Recréer VPC, subnets et VM.
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
/32vers169.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