two/release_notes/0.2.0.md
2026-10-19 16:50:35 +02:00

170 lines
12 KiB
Markdown

# Bael
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
**Serveur DHCP intégré**
- Nouveau binaire `dhcp`, une instance par subnet lancée dans le netns du VPC par l'unit
`dhcp@<netns>_<bridge>`. Il reçoit son bridge et ses deux chemins de fichiers en paramètres :
il ne compose aucun chemin et ignore le netns dans lequel il tourne
- Piloté par l'agent sur une **socket Unix** `/run/two/dhcp/<netns>_<bridge>.sock`, en JSON par
ligne. Ordres idempotents en remplacement intégral : configuration du subnet à sa création,
une réservation par interface à chaque création ou suppression de VM
- **Réservations statiques uniquement**, pas de baux : une MAC inconnue n'obtient rien, et le
serveur reste silencieux plutôt que de répondre par un refus. Aucun `DHCPNAK` n'est émis
- État auto-persisté dans `/run/two/dhcp/<netns>_<bridge>.state`, en écriture atomique et lisible
par le seul `root`. Le fichier appartient au processus, qui le relit à son démarrage ; l'agent
ne l'écrit jamais et se borne à le supprimer — à la création du subnet pour écarter un résidu,
à sa suppression après avoir arrêté l'unit
- La route par défaut est décidée **par interface** et non plus par subnet, ce qui permet de ne
l'annoncer que sur une interface d'une VM multi-réseaux
- L'encodage RFC 3442 de l'option 121 est délégué à `github.com/insomniacslk/dhcp`
**Coexistence avec dnsmasq**
- Nouvelle clé `dhcp.backend`, `dnsmasq` ou `two`, qui choisit le serveur des subnets **créés par
cet agent**. Le défaut est `dnsmasq` : un fichier de configuration de la 0.1.0, non modifié, se
comporte exactement comme avant
- La bascule est une **opération manuelle** sur un hyperviseur vide — l'option ne migre rien, un
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
**Routage inter-subnet entre hyperviseurs : L3VNI (#41)**
- Nouveau champ facultatif `l3vni` sur `POST /vpcs` (1 à 65535, sauf 253-255 : c'est aussi
l'identifiant de la table de routage, et le numéro du RD `<VTEP>:<l3vni>`, sur 16 bits).
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 anycast des subnets `vxlan` (#57)**
- La gateway et l'adresse d'émission sont **calculées** par l'agent : avant-dernière adresse du
`cidr` (`.254` en `/24`) pour la gateway, exposée comme `interface_ip`, et celle d'avant
(`.253`) pour l'adresse d'émission, exposée comme nouveau champ `relay_ip`. Le `cidr` doit
être sans bits d'hôte et faire au plus `/29`
- La gateway est portée par un macvlan `gw-<subnet>` à **MAC anycast** `02:01:00:<VNI sur 24 bits>`,
identique sur tous les hôtes qui portent le subnet : une VM résout toujours sa gateway vers son
hôte. Le bridge garde une MAC propre à l'hôte, `02:03:<IPv4 du VTEP>`, et porte l'adresse
d'émission, d'où partent les requêtes ARP du netns
- Une VM qui reçoit la requête ARP d'un autre hôte ne change plus de gateway : jusqu'ici, elle
envoyait pendant quelques secondes son trafic à cet hôte, coupant métadonnées, renouvellement
DHCP et sessions depuis le netns. Mesuré en lab : aucune perte pendant cette fenêtre
- La MAC anycast est confinée au netns — règles ebtables sur le veth du subnet et entrée FDB
locale dans le bridge — et n'apparaît jamais en EVPN. Le DHCP écoute sur `gw-<subnet>` ; la
route du subnet a la gateway pour source
- Une VM ne peut prendre ni la gateway, ni l'adresse d'émission, ni la `gateway` explicite, ni
l'adresse de réseau ou de broadcast du subnet, ni une adresse hors de son `cidr` (422)
- Le watchdog contrôle le macvlan, sa MAC, les deux adresses et l'entrée FDB
**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
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. Une VM en
`creating`, `deleting` ou `error` n'est pas comparée : sa réservation peut être présente ou
absente sans alerte, le temps que la création ou la suppression aboutisse (#78)
- La socket de contrôle répond à `get-state` et à `probe`, ce dernier montrant sans effet de bord
ce qui serait envoyé à une MAC donnée : adresse, masque, routeur, DNS et routes
- Documentation Sphinx du projet : concepts, architecture, déploiement et exploitation
## 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.**
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
- `probe` annonce explicitement `"served": false` pour une MAC non réservée, au lieu d'omettre le
champ et de le rendre indistinguable d'une réponse tronquée
- **Le serveur DHCP intégré s'arrête proprement** sur `SIGTERM` et `SIGINT` : il ferme sa socket de
contrôle et sa socket UDP avant de sortir. Il mourait jusque-là sans nettoyer, et laissait
`/run/two/dhcp/<netns>_<bridge>.sock` après la suppression du subnet. L'agent supprime aussi
cette socket avec le fichier d'état, ce qui couvre une mort brutale du processus (#77)
## 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
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
fichier, en écriture atomique. Badger a été écarté pour cet usage — une instance par subnet
coûterait une memtable de 64 Mio et quatre goroutines de compaction pour environ un kilo-octet
d'état, dans un `tmpfs`, et laisserait un verrou résiduel après un arrêt brutal
- `internal/subnet` et `internal/vm` ne parlent plus à dnsmasq en direct mais à une interface
`Backend` à deux implémentations
## Périmètre et limites connues
Celles de la 0.1.0 restent valables, sauf mention contraire ci-dessus. S'y ajoutent :
- **L3VNI** : pas de migration à chaud ; la gateway anycast (#57) la prépare côté réseau. MTU
1500 de bout en bout (#56). 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
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é
- La comparaison faite par le watchdog porte sur les **réservations** et non sur la configuration
du subnet : celle-ci dépend de la route par défaut de l'host, dont la lecture au moment du
contrôle produirait de faux écarts. Un serveur dépourvu de configuration est en revanche signalé
- L'option 249 (routes classless de Microsoft) n'est pas émise, comme dnsmasq ne l'émet pas
- Le serveur intégré écoute UDP/67 sans authentification, comme tout serveur DHCP : l'isolation
entre locataires d'un même subnet repose sur les règles ebtables anti-usurpation, inchangées
- `internal/dhcpbackend` n'est testé sous Linux que pour ses appels systemd ; le reste, y compris
le dialogue avec le serveur intégré, est couvert sur toute plateforme
## Mise à jour depuis la 0.1.0
```bash
curl -O https://git.g3e.fr/syonad/two/raw/branch/main/scripts/deploy.sh
bash ./deploy.sh -t 0.2.0
```
Sans `dhcp.backend` ni `bgp` dans `/etc/two/agent.yml`, le comportement est celui de la 0.1.0, à
deux exceptions près, qui touchent les appelants de l'API :
- **`interface_ip` ne se fournit plus pour un subnet `vxlan`** : il est refusé (400), l'agent le
calcule. Le retirer des appels de création, et ne plus placer de VM sur les deux dernières
adresses utilisables du subnet. Il reste obligatoire en `bridge` et `public_ip`
- **un subnet encore utilisé par une VM ne se supprime plus** : supprimer les VM d'abord
Les subnets `vxlan` existants gardent leur adressage et le modèle précédent (gateway sur le
bridge) 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é.