docs: premiere creation de documentation

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

docs/exploitation/api-agent/asynchronisme.rst

@@ -0,0 +1,91 @@
+Modèle asynchrone et codes de retour
+====================================
+
+Toute création et toute suppression sont **asynchrones**. C'est le point qui surprend le plus
+souvent à l'intégration : un ``202`` ne dit pas que la ressource existe, il dit que la demande
+a été acceptée et enregistrée.
+
+Les deux temps d'une requête
+----------------------------
+
+.. mermaid::
+
+   sequenceDiagram
+     participant C as Appelant
+     participant A as API
+     participant W as Worker
+     C->>A: POST /subnets
+     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: état → running (ou error)
+     C->>A: GET /subnets/<name>
+     A-->>C: 200 + state
+
+**Prepare** est synchrone, dans le handler HTTP : il valide l'état, écrit l'état initial en base
+et répond. **Execute** est asynchrone : il fait le travail réseau réel, puis positionne l'état
+final.
+
+Conséquence directe : un échec d'``Execute`` ne peut pas être remonté dans la réponse HTTP. Il
+se lit dans l'état de la ressource, qui passe à ``error``.
+
+Attendre correctement
+---------------------
+
+Il n'y a pas de webhook ni de long-polling : l'appelant interroge ``GET /<type>/<name>`` jusqu'à
+un état stable.
+
+.. code-block:: bash
+
+   until [ "$(curl -sf http://127.0.0.1:8080/subnets/sn-000001 | jq -r .state)" = running ]; do
+     sleep 2
+   done
+
+Trois règles pour un appelant robuste :
+
+* **Toujours borner l'attente.** Côté agent, ``dispatcher.timeout_seconds`` (300 s par défaut)
+  borne les opérations qui attendent une transition ; l'appelant doit avoir sa propre borne.
+* **Traiter ``error`` comme terminal, pas comme un échec transitoire.** Un ``Execute`` en échec
+  ne se rejoue pas tout seul.
+* **Ne pas enchaîner sans vérifier.** Créer un subnet dont le VPC est encore en ``creating``
+  échoue en 422 ; démarrer une VM sur un subnet en ``creating`` ou ``running`` est en revanche
+  accepté.
+
+Codes de retour
+---------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 12 88
+
+   * - Code
+     - Signification
+   * - ``202``
+     - demande acceptée et enregistrée ; l'état passera à ``running`` ou ``error``
+   * - ``200``
+     - lecture réussie (``GET``)
+   * - ``400``
+     - champ obligatoire manquant, corps invalide, ``iface_type`` inconnu, base64 invalide
+   * - ``404``
+     - ressource inexistante
+   * - ``409``
+     - conflit d'existence ou d'état : ressource déjà créée, ou suppression depuis un état qui
+       ne l'autorise pas ; pour un VPC, subnets encore présents
+   * - ``422``
+     - dépendance absente ou pas prête : VPC parent d'un subnet, subnet d'une VM
+   * - ``500``
+     - erreur interne
+
+Le corps d'erreur est uniforme : ``{"error": "…"}``.
+
+Idempotence
+-----------
+
+Les créations ne sont **pas** idempotentes : recréer une ressource existante donne 409, pas 202.
+Un appelant qui rejoue une requête après un timeout réseau doit donc traiter 409 comme
+« déjà fait », après avoir vérifié l'état par un ``GET``.
+
+Les suppressions depuis l'état ``error`` sont acceptées mais **best-effort** : les ressources
+système peuvent n'avoir été créées que partiellement, et il n'y a pas de rollback — voir
+:doc:`/concepts/cycle-de-vie`.

docs/exploitation/api-agent/index.rst

@@ -0,0 +1,21 @@
+API de l'agent
+==============
+
+L'agent expose une API HTTP par hyperviseur. C'est aujourd'hui la seule API de ``two`` ; les
+API de niveau supérieur viendront avec les composants d'orchestration, et seront documentées
+à part.
+
+Elle est **machine-to-machine** : elle est consommée par un autre logiciel, pas par un humain.
+La validation de cohérence des entrées (format des CIDR, plage des VXLAN ID, convention de
+nommage) est à la charge de l'appelant — l'agent ne la refait pas.
+
+.. warning::
+
+   Cette API **n'a aucune authentification**. Voir :doc:`/exploitation/configuration` avant de
+   l'exposer au-delà de la boucle locale.
+
+.. toctree::
+   :maxdepth: 1
+
+   asynchronisme
+   reference

docs/exploitation/api-agent/reference.rst

@@ -0,0 +1,8 @@
+Référence
+=========
+
+Cette page est générée depuis ``api/agent.yaml``, à la racine du dépôt. C'est la source unique
+du contrat : en cas d'écart avec le reste de la documentation, c'est elle qui fait foi.
+
+.. openapi:: ../../../api/agent.yaml
+   :examples:

docs/exploitation/configuration.rst

@@ -0,0 +1,138 @@
+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
+``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.
+
+.. 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
+
+   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.
+
+.. warning::
+
+   À 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
+-----------------------------
+
+.. code-block:: yaml
+
+   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
+----------------
+
+.. 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/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.
+
+Watchdog
+--------
+
+.. code-block:: yaml
+
+   watchdog:
+     enabled: true
+     interval_seconds: 60
+
+Vérification périodique **en lecture seule** — voir :doc:`/exploitation/observabilite`.
+
+Journalisation
+--------------
+
+.. code-block:: yaml
+
+   logger:
+     level: info   # debug, info, warn, error
+     debug: false  # force le niveau debug quel que soit level

docs/exploitation/diagnostic.rst

@@ -0,0 +1,122 @@
+Diagnostic
+==========
+
+Symptôme, cause probable, vérification. Les causes listées sont celles réellement rencontrées.
+
+La ressource part en ``error`` juste après le 202
+-------------------------------------------------
+
+``Execute`` a échoué : la cause est dans le journal de l'agent, pas dans la réponse HTTP.
+
+.. code-block:: bash
+
+   journalctl -u agent -n 100
+
+Cas fréquents :
+
+* subnet en mode ``public_ip`` — la mise en place host n'est pas implémentée, l'échec est attendu ;
+* ``vxlan_id`` déjà utilisé sur l'host ;
+* bridge cible absent : ``iface_type`` inconnu retombé sur ``default_interface``, lui-même
+  inexistant.
+
+Avant toute recréation, émettre un ``DELETE`` : il n'y a pas de rollback, les objets système
+partiellement créés subsistent.
+
+La VM démarre mais n'a pas d'adresse
+------------------------------------
+
+Le DHCP est servi par l'instance ``dnsmasq@`` du subnet.
+
+.. code-block:: bash
+
+   systemctl status 'dnsmasq@<netns>_<bridge>'
+   tail -50 /var/log/dnsmasq-<netns>_<bridge>.log
+   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
+raccordé, VM dans le mauvais netns.
+
+La VM a une adresse mais cloud-init n'applique rien
+---------------------------------------------------
+
+Deux causes distinctes, à écarter dans cet ordre.
+
+**1. La VM porte déjà cet ``instance-id``.** ``instance-id`` vaut le nom de la VM : sur un disque
+déjà provisionné sous le même nom, cloud-init considère l'instance connue et ne rejoue pas le
+user-data. Vérification dans le guest :
+
+.. code-block:: bash
+
+   cloud-init query instance-id
+   ls /var/lib/cloud/instances/
+
+**2. Le serveur de metadata est injoignable.** Depuis le guest :
+
+.. code-block:: bash
+
+   ip route
+   curl -s http://169.254.169.254/latest/meta-data/
+
+La route ``169.254.169.254/32`` doit être présente, avec l'``interface_ip`` du subnet comme
+next-hop. Si elle est absente ou pointe ailleurs, la DNAT posée en ``PREROUTING`` dans le netns
+n'est jamais traversée : la trame est commutée en L2 et le serveur reste injoignable. Voir
+:doc:`/concepts/modes-reseau`.
+
+Depuis l'host, l'instance correspondante :
+
+.. code-block:: bash
+
+   systemctl status 'metadata@<vm>'
+   ls -l /run/two/metadata/<vm>/
+
+Le user-data est servi vide
+---------------------------
+
+Un document fourni explicitement vide est servi vide — ce n'est pas la même chose qu'un document
+absent, qui retombe sur le template. Vérifier le contenu réellement écrit :
+
+.. code-block:: bash
+
+   cat /run/two/metadata/<vm>/user-data
+
+Un base64 invalide, lui, aurait été rejeté en 400 à la création.
+
+La VM ne démarre pas (UEFI)
+---------------------------
+
+``uefi: true`` exige les fichiers OVMF déclarés dans la configuration :
+
+.. code-block:: bash
+
+   ls -l /usr/share/OVMF/OVMF_CODE.fd /usr/share/OVMF/OVMF_VARS.fd
+   ls -l /run/two/vms/efi/
+
+Sur Debian et Ubuntu, le paquet est ``ovmf``.
+
+Le ``DELETE`` renvoie 409
+-------------------------
+
+La suppression n'est autorisée que depuis ``running`` ou ``error``. Depuis ``creating`` ou
+``deleting``, attendre l'état stable. Pour un VPC, tous les subnets doivent être supprimés
+d'abord.
+
+La base et le système ont divergé
+---------------------------------
+
+Le watchdog signale une ressource ``running`` absente du système. Il ne répare rien : la
+correction est un ``DELETE`` explicite suivi d'une recréation. Après un redémarrage de l'agent,
+les ressources restées transitoires sont basculées en ``error`` par la migration de démarrage —
+elles n'ont pas forcément échoué, elles ont été interrompues.
+
+L'agent ne redémarre pas après un arrêt brutal
+----------------------------------------------
+
+Badger rejoue son journal au démarrage : c'est normal et attendu, notamment si le budget d'arrêt
+précédent a été dépassé et que la base n'a pas été fermée. Si le démarrage échoue vraiment, le
+message se trouve dans ``journalctl -u agent``.
+
+.. note::
+
+   Les VM ne sont pas réattachées au redémarrage de l'agent : un processus QEMU survivant à
+   l'agent n'est plus piloté par lui.

docs/exploitation/observabilite.rst

@@ -0,0 +1,83 @@
+Observabilité
+=============
+
+Métriques Prometheus
+--------------------
+
+Exposées sur le port ``prometheus.port`` (9090 par défaut), alimentées par l'état lu en base :
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Métrique
+     - Description
+   * - ``syonad_vpcs_total``
+     - nombre de VPC, par état
+   * - ``syonad_subnets_total``
+     - nombre de subnets, par état
+   * - ``syonad_vms_total``
+     - nombre de VM, par état
+
+Les états sont ceux du :doc:`cycle de vie </concepts/cycle-de-vie>`. Une valeur non nulle et
+durable sur ``error`` est l'alerte la plus utile à poser ; une valeur durable sur ``creating``
+ou ``deleting`` signale une opération qui n'aboutit pas.
+
+Watchdog
+--------
+
+Une goroutine périodique vérifie que les ressources marquées ``running`` en base existent
+toujours sur le système, et **notifie les écarts sans jamais réparer**.
+
+.. code-block:: yaml
+
+   watchdog:
+     enabled: true
+     interval_seconds: 60
+
+Il contrôle notamment l'existence des network namespaces, des liens réseau des subnets, des taps
+de VM et la réponse des units systemd associées.
+
+.. note::
+
+   Un écart persistant est signalé **à chaque tick**, sans déduplication. Le volume de
+   notifications est donc proportionnel à la durée de l'anomalie : c'est voulu, mais cela veut
+   dire qu'une alerte doit agréger, pas compter.
+
+Le watchdog étant strictement en lecture seule, une divergence entre la base et le système
+subsiste jusqu'à une action explicite (``DELETE`` puis recréation).
+
+Journaux
+--------
+
+``slog`` structuré, niveau réglé par ``logger.level`` (``debug``, ``info``, ``warn``, ``error``),
+``logger.debug: true`` forçant ``debug``.
+
+.. code-block:: bash
+
+   journalctl -u agent -f
+   journalctl -u 'metadata@i-web' -n 50
+   tail -f /var/log/dnsmasq-vp-admin_br-sn000001.log
+
+Inspection de la base
+---------------------
+
+En ligne de commande, sur l'host :
+
+.. code-block:: bash
+
+   /opt/two/bin/db -conf /etc/two/agent.yml
+
+.. warning::
+
+   ``db`` ouvre directement la base Badger. **Ne pas l'utiliser pendant que l'agent tourne** :
+   deux processus ne doivent pas ouvrir la même instance.
+
+L'API d'administration donne la même lecture sans ce risque, quand elle est activée :
+
+.. code-block:: bash
+
+   curl -s 'http://127.0.0.1:9091/db?prefix=vm/'
+
+Elle expose l'intégralité des valeurs, **y compris les hashs de mot de passe** — cf.
+:doc:`/exploitation/configuration`.

docs/exploitation/services.rst

@@ -0,0 +1,91 @@
+Services systemd
+================
+
+Trois units, installées sous ``/opt/two/bin`` par ``deploy.sh``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 32 40
+
+   * - Unit
+     - Instance ``%i``
+     - Rôle
+   * - ``agent.service``
+     - —
+     - processus principal : API, dispatcher, exécution, watchdog
+   * - ``dnsmasq@.service``
+     - ``<netns>_<bridge>``
+     - dnsmasq lancé dans le netns du VPC, un par subnet
+   * - ``metadata@.service``
+     - ``<nom de la VM>``
+     - serveur de metadata cloud-init, un par VM
+
+Les instances sont créées et pilotées par l'agent au fil des créations de subnets et de VM : il
+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 '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 :
+
+.. list-table::
+   :widths: 40 60
+
+   * - Configuration
+     - ``/etc/dnsmasq.d/<netns>_<bridge>.conf``
+   * - Baux
+     - ``/run/dnsmasq-<netns>_<bridge>.leases``
+   * - Journal
+     - ``/var/log/dnsmasq-<netns>_<bridge>.log``
+   * - PID
+     - ``/run/dnsmasq-<netns>_<bridge>.pid``
+
+Le fichier de baux et le journal sont les deux premiers endroits à regarder quand une VM n'obtient
+pas d'adresse.
+
+QEMU n'est pas une unit
+-----------------------
+
+Les processus QEMU sont lancés par ``systemd-run --scope``, **jamais** en unit transitoire. Un
+scope est exécuté par le processus appelant et hérite donc du network namespace posé par
+l'agent ; une unit transitoire, forkée par PID 1, démarrerait dans le netns racine et ne verrait
+pas le tap de la VM.
+
+Conséquence pratique : les VM n'apparaissent pas dans ``systemctl list-units`` mais dans
+``systemd-cgls``, et elles ne survivent pas à un ``systemctl stop agent`` suivi d'un
+redémarrage — l'agent ne réattache pas les VM existantes.
+
+Sockets par VM
+--------------
+
+.. code-block:: text
+
+   /run/two/vms/serial/<vm>.sock     console série
+   /run/two/vms/monitor/<vm>.sock    monitor QEMU
+   /run/two/vms/qmp/<vm>.sock        QMP (utilisé par l'agent)
+
+.. code-block:: bash
+
+   socat -,raw,echo=0 UNIX-CONNECT:/run/two/vms/serial/i-web.sock
+
+Arrêt de l'agent
+----------------
+
+L'ordre d'arrêt est imposé : serveurs HTTP, puis drainage des workers, puis fermeture de la base.
+Si le budget d'arrêt est dépassé, la base **n'est pas fermée** — fermer Badger sous un écrivain
+concurrent est pire qu'un rejeu du journal au démarrage suivant. Un message à ce sujet dans le
+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
+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.