f-41: docs: notes de version 0.2.0 (L3VNI, BGP par l'agent, MAC de gateway), clés des interfaces de VM #41
All checks were successful
Documentation / publish (push) Successful in 1m28s
Release Pipeline / set-release-target (push) Successful in 2s
Release Pipeline / upload-assets (dhcp@.service, systemd/dhcp@.service) (push) Successful in 7s
Release Pipeline / upload-assets (dnsmasq@.service, systemd/dnsmasq@.service) (push) Successful in 7s
Release Pipeline / upload-assets (run-dnsmasq-in-netns.sh, scripts/run-dnsmasq-in-netns.sh) (push) Successful in 7s
Release Pipeline / upload-assets (agent.service, systemd/agent.service) (push) Successful in 7s
Release Pipeline / upload-assets (metadata@.service, systemd/metadata@.service) (push) Successful in 7s
Release Pipeline / upload-assets (run-dhcp-in-netns.sh, scripts/run-dhcp-in-netns.sh) (push) Successful in 7s
Release Pipeline / checksums (push) Successful in 9s
Release Pipeline / build (agent, amd64, linux) (push) Successful in 0s
Release Pipeline / build (dhcp, amd64, linux) (push) Successful in 0s
Release Pipeline / build (metadata, amd64, linux) (push) Successful in 0s
Release Pipeline / release (push) Successful in 29s
Release Pipeline / publish (push) Successful in 0s
Release Pipeline / build (push) Successful in 2m26s

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
This commit is contained in:
GnomeZworc 2026-10-12 01:10:34 +02:00
commit 1828053e6d
Signed by: nicolas.boufideline
GPG key ID: 4406BBBF8845D632
2 changed files with 73 additions and 9 deletions

View file

@ -22,9 +22,10 @@ de sérialisation structurée.
subnet/<name>/dhcp/<ip> → <mac> subnet/<name>/dhcp/<ip> → <mac>
vm/<name>/state → creating | running | error | deleting | deleted vm/<name>/state → creating | running | error | deleting | deleted
vm/<name>/subnet → <subnet-name> vm/<name>/nic/<i>/subnet → <subnet-name> (une interface par index, ordre du tableau interfaces)
vm/<name>/tap_id → <int> vm/<name>/nic/<i>/ip → <ip>
vm/<name>/ip → <ip> vm/<name>/nic/<i>/primary → "true" (exactement une interface ; absent sur les autres)
vm/<name>/nic/<i>/tap_id → <int> (alloué au premier démarrage, puis conservé)
vm/<name>/metadata_port → <port> vm/<name>/metadata_port → <port>
vm/<name>/disk/<dev> → <path> (une clé par disque : sda, vda, …) vm/<name>/disk/<dev> → <path> (une clé par disque : sda, vda, …)
vm/<name>/memory → <int> (Mo) vm/<name>/memory → <int> (Mo)
@ -37,9 +38,14 @@ de sérialisation structurée.
Règles Règles
------ ------
**Pas de duplication.** Une ressource ne stocke que ce qui lui est propre. Une VM garde le lien **Pas de duplication.** Une ressource ne stocke que ce qui lui est propre. Une interface de VM
``vm/<name>/subnet`` ; le VPC, le bridge et l'``interface_ip`` sont lus depuis le subnet, leur garde le lien ``vm/<name>/nic/<i>/subnet`` ; le VPC, le mode, le bridge et l'``interface_ip`` sont
source canonique. lus depuis le subnet, leur source canonique. De même, la L3VNI d'un VPC n'est stockée que sous
``vpc/<name>/l3vni`` : RT, RD, MAC de routeur et table de routage en sont calculés.
**Ancien schéma des VM.** Avant le multi-interfaces, une VM portait directement ``subnet``, ``ip``
et ``tap_id``. L'agent les migre au démarrage vers ``nic/0/…``, marquée ``primary``, avant
d'ouvrir son API ; une VM qui a déjà des clés ``nic/`` est laissée telle quelle.
**Les états passent par ``state``.** Toujours ``state.Set`` / ``state.Get`` : ``Set`` refuse une **Les états passent par ``state``.** Toujours ``state.Set`` / ``state.Get`` : ``Set`` refuse une
valeur hors énumération, ``Get`` refuse de retourner une valeur non reconnue. ``error`` n'est valeur hors énumération, ``Get`` refuse de retourner une valeur non reconnue. ``error`` n'est

View file

@ -1,6 +1,7 @@
# Bael # Bael
Serveur DHCP intégré, en coexistence avec dnsmasq, et documentation du projet. Serveur DHCP intégré, en coexistence avec dnsmasq ; routage inter-subnet entre hyperviseurs par
L3VNI, avec une configuration BGP pilotée par l'agent ; documentation du projet.
## Fonctionnalités ## Fonctionnalités
@ -31,8 +32,44 @@ Serveur DHCP intégré, en coexistence avec dnsmasq, et documentation du projet.
subnet déjà créé reste servi par le serveur qui l'a été. La procédure est documentée subnet déjà créé reste servi par le serveur qui l'a été. La procédure est documentée
- Toute valeur autre que `dnsmasq` ou `two` fait échouer le démarrage de l'agent - Toute valeur autre que `dnsmasq` ou `two` fait échouer le démarrage de l'agent
**Routage inter-subnet entre hyperviseurs : L3VNI (#41)**
- Nouveau champ facultatif `l3vni` sur `POST /vpcs` (1 à 16777215, sauf 253-255 : c'est aussi
l'identifiant de la table de routage). Absent, le VPC se comporte comme avant. Une L3VNI déjà
portée par un VPC de l'agent est refusée (409), comme un `l3vni` demandé sans section `bgp`
- Pour un VPC routé, l'agent pose sur l'hyperviseur une VRF (table = L3VNI), un bridge à la MAC de
routeur `02:02:<IPv4 du VTEP>`, le VXLAN de la L3VNI, un lien de transit `169.254.0.1/30` ↔
`169.254.0.2/30` vers le netns et la route du `cidr` du VPC dans le netns ; FRR reçoit la VRF,
sa `vni`, une instance `router bgp … vrf` (RD `<VTEP>:<l3vni>`, RT `<asn>:<l3vni>`) et l'export
des routes du `cidr`. Un hyperviseur n'a plus besoin de porter un subnet pour joindre ses VM
- Routes annoncées : le `/24` de chaque subnet `vxlan` à sa création, le `/32` de chaque interface
de VM juste avant son passage en `running` ; retirés en premier à la suppression
- La suppression d'un VPC routé retire la configuration de routage de FRR, puis les interfaces,
puis la VRF de FRR — dans cet ordre, faute de quoi `bgpd` plante (FRR 10.7.1)
**Configuration BGP pilotée par l'agent**
- Nouvelle section facultative `bgp` (`asn`, `route_reflectors`). Présente, l'agent applique à
chaque démarrage, par `vtysh`, la base BGP de l'hyperviseur (router-id = VTEP, peer-group
`fabric` vers les route reflectors, EVPN, `advertise-all-vni`) et l'enregistre :
`/etc/frr/frr.conf` devient un fichier généré. Un route reflector retiré de la liste est retiré
de FRR. Absente, l'agent ne touche pas à FRR
- Le démarrage échoue si la section est incomplète, si FRR tourne déjà sous un autre AS ou si
`vtysh` ne répond pas
**Gateway des subnets `vxlan`**
- Le bridge du subnet porte une **MAC propre à l'hôte**, `02:03:<IPv4 du VTEP>`, posée à la
création du subnet. Une MAC identique sur tous les hôtes (anycast) a été essayée puis retirée :
annoncée en double en EVPN, elle empêchait aussi une gateway de joindre en L2 une VM d'un autre
hôte (#57)
**Exploitation** **Exploitation**
- Le watchdog contrôle aussi, avec une section `bgp` : les sessions vers les route reflectors ;
pour chaque VPC routé, les interfaces de la VRF et l'état de la L3VNI dans FRR (type, état, MAC
de routeur) ; la cohérence entre routes exportées et ressources `running` — une route exportée
sans propriétaire est signalée comme **trou noir**, une route attendue absente comme manquante
- Le watchdog interroge le serveur DHCP intégré et compare les réservations servies à celles que - Le watchdog interroge le serveur DHCP intégré et compare les réservations servies à celles que
la base implique. Il nomme ce qui diverge — ordre perdu à la création, ordre perdu à la la base implique. Il nomme ce qui diverge — ordre perdu à la création, ordre perdu à la
suppression, adresse ou route par défaut divergente — et reste en lecture seule suppression, adresse ou route par défaut divergente — et reste en lecture seule
@ -42,6 +79,9 @@ Serveur DHCP intégré, en coexistence avec dnsmasq, et documentation du projet.
## Correctifs ## Correctifs
- **Suppression d'un subnet refusée tant qu'une VM non supprimée l'utilise** (409, avec la liste
des VM), pour tous les subnets : garantit qu'une route `/32` est retirée avant le `/24` de son
subnet, ce qui évite un trou noir partiel mesuré en lab
- **Un fichier de configuration présent mais invalide fait désormais échouer le démarrage.** - **Un fichier de configuration présent mais invalide fait désormais échouer le démarrage.**
Jusqu'en 0.1.0 l'erreur de lecture était ignorée : l'agent tournait alors entièrement sur ses Jusqu'en 0.1.0 l'erreur de lecture était ignorée : l'agent tournait alors entièrement sur ses
valeurs par défaut sans le dire, ce qui rendait indétectable une simple tabulation d'indentation valeurs par défaut sans le dire, ce qui rendait indétectable une simple tabulation d'indentation
@ -50,6 +90,11 @@ Serveur DHCP intégré, en coexistence avec dnsmasq, et documentation du projet.
## Changements internes ## Changements internes
- Nouveaux paquets `internal/frr` (seul point d'appel à `vtysh` : génération des commandes,
démontage ordonné, relecture de la configuration après démontage) et `internal/sysctl` ; une
remarque de `vtysh` (« Configuration applied with notes ») n'est pas une erreur, et la
suppression d'une instance BGP de VRF est réessayée tant que `bgpd` n'a pas libéré la L3VNI
- Les tests du dispatcher arrêtent les workers avant de fermer la base (#47)
- Le module passe à **Go 1.25**, exigé par la bibliothèque DHCP retenue. La version de Go du - Le module passe à **Go 1.25**, exigé par la bibliothèque DHCP retenue. La version de Go du
workflow de build, restée à 1.21 alors que le module en demandait davantage, est alignée workflow de build, restée à 1.21 alors que le module en demandait davantage, est alignée
- Nouveau paquet `pkg/db/statefile` : persistance générique d'un état de composant dans un - Nouveau paquet `pkg/db/statefile` : persistance générique d'un état de composant dans un
@ -63,6 +108,14 @@ Serveur DHCP intégré, en coexistence avec dnsmasq, et documentation du projet.
Celles de la 0.1.0 restent valables, sauf mention contraire ci-dessus. S'y ajoutent : Celles de la 0.1.0 restent valables, sauf mention contraire ci-dessus. S'y ajoutent :
- **L3VNI** : pas de migration à chaud ; le cache ARP d'une VM qui changerait d'hôte reste à
traiter (#57). MTU 1500 de bout en bout (#56). Un seul route reflector qualifié (#54). Le
transit `169.254.0.0/30` étant identique sur tous les hôtes, les ICMP des sauts distants sont
rejetés comme « martiens » (traceroute partiel)
- Avec une section `bgp`, l'agent ne démarre pas sans FRR et `agent.service` ne le relance pas :
au démarrage, l'ordre est migration réseau, puis FRR, puis l'agent (#52)
- `bootstrap_kvm.sh` active `net.ipv4.ip_forward` en global ; le forwarding que l'agent active
sur les seules interfaces de la VRF n'en restreint donc pas la portée
- **dnsmasq n'est pas retiré** et reste un paquet requis : le backend intégré ne sert que les - **dnsmasq n'est pas retiré** et reste un paquet requis : le backend intégré ne sert que les
subnets créés après la bascule, et le retour arrière suppose dnsmasq installé subnets créés après la bascule, et le retour arrière suppose dnsmasq installé
- Pas de DNS, pas de pool dynamique, pas de PXE, pas de DHCPv6 dans le serveur intégré - Pas de DNS, pas de pool dynamique, pas de PXE, pas de DHCPv6 dans le serveur intégré
@ -82,6 +135,11 @@ curl -O https://git.g3e.fr/syonad/two/raw/branch/main/scripts/deploy.sh
bash ./deploy.sh -t 0.2.0 bash ./deploy.sh -t 0.2.0
``` ```
Aucune action n'est requise : sans `dhcp.backend` dans `/etc/two/agent.yml`, le comportement est Aucune action n'est requise : sans `dhcp.backend` ni `bgp` dans `/etc/two/agent.yml`, le
celui de la 0.1.0. Pour passer au serveur intégré, suivre la procédure de bascule dans la comportement est celui de la 0.1.0, à une exception près — **un subnet encore utilisé par une VM
ne se supprime plus** : supprimer les VM d'abord. Les subnets `vxlan` existants gardent leur MAC
de gateway jusqu'à leur recréation.
Pour router entre hyperviseurs : ajouter la section `bgp`, réduire `frr.conf` à `hostname` et
`log` (l'agent pose le reste), puis créer les VPC avec `l3vni`. Pour passer au serveur intégré, suivre la procédure de bascule dans la
documentation d'exploitation — elle suppose un hyperviseur vidé. documentation d'exploitation — elle suppose un hyperviseur vidé.