two/docs/exploitation/configuration.rst
2026-10-25 23:47:54 +01:00

304 lines
11 KiB
ReStructuredText

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.
.. warning::
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
---------------
.. code-block:: yaml
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
--------
.. code-block:: yaml
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.
.. warning::
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
-----------------------
.. code-block:: yaml
worker:
count: 4
buffer_size: 100
times:
timeout_vms_stop: 300
next_vms_shutdown: 30
timeout_subnet_stop: 360
timeout_vpc_stop: 420
timeout_subnet_start: 300
timeout_vms_start: 300
poll_interval: 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.
La section ``times`` règle, en secondes, les attentes des commandes asynchrones :
``timeout_vms_stop``
arrêt propre d'une VM : au-delà, QEMU reçoit un ``quit`` QMP.
``next_vms_shutdown``
intervalle entre deux ``system_powerdown`` pendant cet arrêt. Un invité qui n'écoutait pas
encore l'ACPI au premier appui (firmware, chargeur de démarrage) s'éteint au suivant.
``timeout_subnet_stop``
suppression d'un subnet : attente de ses VM encore en ``deleting``.
``timeout_vpc_stop``
suppression d'un VPC : attente de ses subnets encore en ``deleting``.
``timeout_subnet_start``
création d'un subnet : attente de son VPC ``running``.
``timeout_vms_start``
création d'une VM : attente des subnets de ses interfaces ``running``.
``poll_interval``
pas de toutes ces attentes.
Chaque valeur doit être strictement positive, et ``next_vms_shutdown`` inférieur à
``timeout_vms_stop`` ; sinon l'agent refuse de démarrer. Les attentes s'enchaînent — une VM,
puis son subnet, puis le VPC : garder ``timeout_vms_stop`` < ``timeout_subnet_stop`` <
``timeout_vpc_stop`` pour qu'une suppression en cascade envoyée d'un coup aboutisse.
L'ancienne section ``dispatcher`` (``timeout_seconds``, ``poll_seconds``) n'est plus lue : restée
dans un fichier, elle est ignorée.
.. warning::
À l'expiration de ``timeout_vms_stop``, 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
-----------------------------
.. code-block:: yaml
default_interface: br-000000
interfaces:
vms: br-000000
internet: br-public
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.
``internet`` désigne aussi le **bridge public**, celui qui porte ``vxlan-public`` et où chaque
VPC raccorde son veth ``vp-<id>-e`` (:doc:`/concepts/vpc-subnet-vm`). Pour lui, une clé absente
ou vide vaut ``br-public``, **jamais** ``default_interface`` : le segment public ne doit pas
tomber sur l'underlay. À garder égal au ``-P`` de ``deploy.sh``.
MTU
---
.. code-block:: yaml
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
--------------------
.. code-block:: yaml
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
:doc:`/deploiement/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.
.. warning::
``/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
----------------
.. code-block:: yaml
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
------------
.. code-block:: yaml
dhcp:
backend: two # ou dnsmasq
Choisit qui sert le DHCP des subnets **créés par cet agent** :
.. list-table::
:header-rows: 1
:widths: 14 44 42
* - 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 :doc:`diagnostic`.
Bascule d'un backend à l'autre
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
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 :
.. code-block:: bash
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
--------
.. code-block:: yaml
watchdog:
enabled: true
interval_seconds: 60
Vérification périodique **en lecture seule** — voir :doc:`/exploitation/observabilite`.
**Désactivée par défaut** (``enabled: false``) : sans cette section, aucun contrôle ne tourne.
Journalisation
--------------
.. code-block:: yaml
logger:
level: info # debug, info, warn, error
debug: false # force le niveau debug quel que soit level