f-46: doc: document the dhcp backend and its switch procedure #46

Note de version 0.2.0 (Bael), et reprise des huit pages de docs/ qui parlaient
de dnsmasq ou du DHCP.

Ajouts de fond : la section Backend DHCP de la page de configuration, avec la
procédure de bascule manuelle et l'avertissement qu'elle ne migre rien ; la
section du serveur intégré dans les services ; et dans la page de diagnostic
comment interroger la socket de contrôle, probe étant le point de départ le plus
rapide quand une VM n'obtient pas d'adresse.

Le nom de version se déduit du rang, pas du numéro : deuxième release, deuxième
nom de codenames.md.

Construit avec sphinx-build -W --keep-going, sans avertissement.

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>

docs/exploitation/api-agent/asynchronisme.rst

@@ -18,7 +18,7 @@ Les deux temps d'une requête
      A->>A: Prepare — valide, écrit "creating"
      A-->>C: 202 + ressource en creating
      A->>W: Dispatch (file d'attente)
-     W->>W: Execute — netns, netif, dnsmasq
+     W->>W: Execute — netns, netif, dhcp
      W->>W: état → running (ou error)
      C->>A: GET /subnets/<name>
      A-->>C: 200 + state

docs/exploitation/configuration.rst

@@ -1,12 +1,19 @@
 Configuration
 =============
 
-Un seul fichier, ``/etc/two/agent.yml``, partagé par les trois binaires : ``agent -config``,
-``metadata -conf`` et ``db -conf``. Le fichier de référence commenté est
+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
@@ -117,6 +124,71 @@ Les chemins OVMF sont nécessaires aux VM démarrées avec ``uefi: true`` (paque
 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: dnsmasq   # ou two
+
+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 ``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 :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
 --------
 

docs/exploitation/diagnostic.rst

@@ -25,7 +25,9 @@ partiellement créés subsistent.
 La VM démarre mais n'a pas d'adresse
 ------------------------------------
 
-Le DHCP est servi par l'instance ``dnsmasq@`` du subnet.
+Le DHCP est servi par une instance dédiée au subnet. Quelle unit selon ``dhcp.backend`` :
+
+**Backend ``dnsmasq``**
 
 .. code-block:: bash
 
@@ -34,7 +36,31 @@ Le DHCP est servi par l'instance ``dnsmasq@`` du subnet.
    cat /run/dnsmasq-<netns>_<bridge>.leases
    cat /etc/dnsmasq.d/<netns>_<bridge>.conf
 
-Si dnsmasq ne voit passer aucune requête, le problème est en amont : tap absent, bridge non
+**Backend ``two``**
+
+.. code-block:: bash
+
+   systemctl status 'dhcp@<netns>_<bridge>'
+   journalctl -u 'dhcp@<netns>_<bridge>' -n 50
+
+   # Ce que le serveur a réellement en mémoire
+   echo '{"verb":"get-state"}' \
+     | socat - UNIX-CONNECT:/run/two/dhcp/<netns>_<bridge>.sock | jq .
+
+   # Ce qu'il enverrait à une MAC donnée, sans effet de bord
+   echo '{"verb":"probe","mac":"00:22:33:00:00:0A"}' \
+     | socat - UNIX-CONNECT:/run/two/dhcp/<netns>_<bridge>.sock | jq .lease
+
+``probe`` est le point de départ le plus rapide : il montre l'adresse, le masque, le routeur, les
+DNS et les routes classless tels qu'ils partiraient. Une réponse ``"served": false`` signifie que
+la MAC n'est pas réservée — l'ordre ``set-host`` n'a jamais atteint le serveur, ou la VM n'a pas
+été créée par cet agent.
+
+Le watchdog signale ces écarts de lui-même, à chaque tick, en comparant l'état servi à la base :
+``dhcp reservation missing on the server``, ``stale dhcp reservation``, ``dhcp reservation
+diverges``. Regarder ses notifications avant de sonder à la main.
+
+Si le serveur ne voit passer aucune requête, le problème est en amont : tap absent, bridge non
 raccordé, VM dans le mauvais netns.
 
 La VM a une adresse mais cloud-init n'applique rien

docs/exploitation/observabilite.rst

@@ -57,7 +57,8 @@ Journaux
 
    journalctl -u agent -f
    journalctl -u 'metadata@i-web' -n 50
-   tail -f /var/log/dnsmasq-vp-admin_br-sn000001.log
+   tail -f /var/log/dnsmasq-vp-admin_br-sn000001.log        # backend dnsmasq
+   journalctl -fu 'dhcp@vp-admin_br-sn000001'             # backend two
 
 Inspection de la base
 ---------------------

docs/exploitation/services.rst

@@ -1,7 +1,8 @@
 Services systemd
 ================
 
-Trois units, installées sous ``/opt/two/bin`` par ``deploy.sh``.
+Quatre units, installées sous ``/opt/two/bin`` par ``deploy.sh``. Les deux units DHCP
+s'excluent : celle qui tourne dépend de ``dhcp.backend`` (voir :doc:`configuration`).
 
 .. list-table::
    :header-rows: 1
@@ -15,7 +16,10 @@ Trois units, installées sous ``/opt/two/bin`` par ``deploy.sh``.
      - processus principal : API, dispatcher, exécution, watchdog
    * - ``dnsmasq@.service``
      - ``<netns>_<bridge>``
-     - dnsmasq lancé dans le netns du VPC, un par subnet
+     - dnsmasq lancé dans le netns du VPC, un par subnet — backend ``dnsmasq``
+   * - ``dhcp@.service``
+     - ``<netns>_<bridge>``
+     - serveur DHCP intégré, un par subnet — backend ``two``
    * - ``metadata@.service``
      - ``<nom de la VM>``
      - serveur de metadata cloud-init, un par VM
@@ -26,14 +30,15 @@ n'y a pas à les démarrer à la main en fonctionnement normal.
 .. code-block:: bash
 
    systemctl status agent
-   systemctl status 'dnsmasq@vp-admin_br-sn000001'
+   systemctl status 'dnsmasq@vp-admin_br-sn000001'   # backend dnsmasq
+   systemctl status 'dhcp@vp-admin_br-sn000001'      # backend two
    systemctl status 'metadata@i-web'
 
 dnsmasq
 -------
 
-Le script ``run-dnsmasq-in-netns.sh`` entre dans le netns puis exécute dnsmasq avec un fichier
-de configuration par subnet, généré par l'agent :
+Backend historique. Le script ``run-dnsmasq-in-netns.sh`` entre dans le netns puis exécute dnsmasq
+avec un fichier de configuration par subnet, généré par l'agent :
 
 .. list-table::
    :widths: 40 60
@@ -50,6 +55,42 @@ de configuration par subnet, généré par l'agent :
 Le fichier de baux et le journal sont les deux premiers endroits à regarder quand une VM n'obtient
 pas d'adresse.
 
+Serveur DHCP intégré
+--------------------
+
+Backend ``two``. Le script ``run-dhcp-in-netns.sh`` entre dans le netns puis exécute le binaire
+``dhcp``, à qui il passe le bridge à servir et ses deux chemins de fichiers — il ne déduit rien et
+ignore le netns dans lequel il tourne :
+
+.. code-block:: bash
+
+   /opt/two/bin/dhcp -conf /etc/two/agent.yml \
+     -interface br-sn000001 \
+     -state /run/two/dhcp/vp-admin_br-sn000001.state \
+     -socket /run/two/dhcp/vp-admin_br-sn000001.sock
+
+.. list-table::
+   :widths: 40 60
+
+   * - Socket de contrôle
+     - ``/run/two/dhcp/<netns>_<bridge>.sock``
+   * - État
+     - ``/run/two/dhcp/<netns>_<bridge>.state``
+   * - Journal
+     - ``journalctl -u 'dhcp@<netns>_<bridge>'``
+
+Il n'y a **ni fichier de configuration ni fichier de baux**. L'agent pousse l'état désiré sur la
+socket de contrôle : la configuration du subnet à sa création, une réservation par interface à
+chaque création ou suppression de VM. Les réservations sont statiques — une MAC inconnue n'obtient
+rien, et le serveur reste silencieux plutôt que de répondre par un refus.
+
+Le fichier d'état **appartient au processus**, qui l'écrit et le relit à son démarrage. L'agent ne
+l'écrit jamais ; il le supprime seulement, à la création du subnet pour écarter un résidu et à sa
+suppression après avoir arrêté l'unit. Il vit dans ``/run`` parce qu'il n'a aucun sens sans le
+netns, qui ne survit pas au redémarrage de l'host.
+
+Diagnostic : voir :doc:`diagnostic`, qui montre comment interroger la socket.
+
 QEMU n'est pas une unit
 -----------------------
 
@@ -86,6 +127,6 @@ journal au moment d'un ``stop`` n'est donc pas une anomalie.
 Mise à jour
 -----------
 
-``deploy.sh`` relève les instances ``dnsmasq@`` et ``metadata@`` actives **avant** d'arrêter les
+``deploy.sh`` relève les instances ``dnsmasq@``, ``dhcp@`` et ``metadata@`` actives **avant** d'arrêter les
 services, et les redémarre ensuite : c'est la seule façon de savoir lesquelles relancer. Arrêter
 les services à la main avant de lancer le script fait perdre cette liste.