From 2ce5024d91c3c3b1e3e48355ec1df8fe4b2e4205 Mon Sep 17 00:00:00 2001 From: GnomeZworc Date: Fri, 16 Oct 2026 10:44:45 +0200 Subject: [PATCH] =?UTF-8?q?f-57:=20doc:=20gateway=20anycast=20(modes=20r?= =?UTF-8?q?=C3=A9seau,=20invariants,=20diagnostic),=20contrat=20d'API=20et?= =?UTF-8?q?=20notes=20de=20version=200.2.0=20#57?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: GnomeZworc --- api/agent.yaml | 37 +++++++++---- docs/architecture/contraintes.rst | 11 ++++ docs/concepts/modes-reseau.rst | 90 ++++++++++++++++++++++++++----- docs/concepts/vpc-subnet-vm.rst | 7 +-- docs/exploitation/diagnostic.rst | 32 +++++++++++ release_notes/0.2.0.md | 42 ++++++++++----- 6 files changed, 182 insertions(+), 37 deletions(-) diff --git a/api/agent.yaml b/api/agent.yaml index 714b8f6..0f034c3 100644 --- a/api/agent.yaml +++ b/api/agent.yaml @@ -146,7 +146,10 @@ paths: schema: $ref: "#/components/schemas/Error" "422": - description: Subnet not found, or not in creating/running state + description: > + Subnet not found, or not in creating/running state; or an interface IP outside the + subnet CIDR, equal to its network or broadcast address, or reserved by the subnet + (interface_ip, relay_ip, gateway) content: application/json: schema: @@ -229,7 +232,9 @@ paths: schema: $ref: "#/components/schemas/Subnet" "400": - description: Missing required field or unknown iface_type + description: > + Missing required field; interface_ip missing on a bridge or public_ip subnet, or + supplied on a vxlan subnet (it is computed) content: application/json: schema: @@ -241,7 +246,9 @@ paths: schema: $ref: "#/components/schemas/Error" "422": - description: Parent VPC does not exist or is not ready + description: > + Unknown mode; parent VPC does not exist or is not ready; invalid CIDR, or a vxlan + CIDR smaller than /29 content: application/json: schema: @@ -349,7 +356,7 @@ components: SubnetCreateRequest: type: object - required: [name, vpc, interface_ip, cidr] + required: [name, vpc, cidr] properties: name: type: string @@ -381,11 +388,16 @@ components: interface_ip: type: string format: ipv4 - description: Gateway IP for the subnet + description: > + Gateway IP for the subnet. Required in bridge and public_ip modes. Rejected in vxlan + mode (400): the agent computes it as the last usable address of the CIDR + (broadcast - 1), carried by an anycast gateway identical on every host. example: "10.10.10.1" cidr: type: string - description: Subnet CIDR block + description: > + Subnet CIDR block. In vxlan mode, without host bits and at most /29: the last two + usable addresses are reserved for the gateway and the relay address. example: "10.10.10.0/24" default_route: type: boolean @@ -403,7 +415,7 @@ components: Optional next-hop for the default route. Only used when default_route is true; supplied with default_route false, it is ignored. Not validated by the agent: reachability and coherence with the subnet CIDR are the caller's responsibility. - example: "10.10.10.254" + example: "10.10.10.1" Subnet: type: object @@ -432,7 +444,14 @@ components: example: br-000000 interface_ip: type: string - example: "10.10.10.1" + description: Subnet gateway. In vxlan mode, computed by the agent (broadcast - 1). + example: "10.10.10.254" + relay_ip: + type: string + description: > + vxlan mode only (broadcast - 2): address the subnet uses to reach guests on other + hosts, carried by the bridge of each host. Absent on subnets created before it existed. + example: "10.10.10.253" cidr: type: string example: "10.10.10.0/24" @@ -441,7 +460,7 @@ components: example: false gateway: type: string - example: "10.10.10.254" + example: "10.10.10.1" VMCreateRequest: type: object diff --git a/docs/architecture/contraintes.rst b/docs/architecture/contraintes.rst index 698cf4a..c83fec6 100644 --- a/docs/architecture/contraintes.rst +++ b/docs/architecture/contraintes.rst @@ -23,6 +23,17 @@ Réseau * **La route vers le CIDR du VPC garde ``interface_ip`` comme next-hop** dans tous les modes sauf ``bridge`` : sur un subnet à IP publique, le trafic interne ne doit pas sortir par la gateway publique. +* **La MAC anycast d'une gateway ``vxlan`` ne sort jamais du netns** : règles ebtables sur le veth + du subnet (source anycast rejetée en entrée et en sortie) **et** entrée FDB locale dans le bridge + du netns. Sans l'entrée FDB, que le macvlan ne crée pas, toute trame d'une VM vers sa gateway est + inondée vers le fabric et traitée par la gateway de chaque hôte. +* **La gateway ``vxlan`` n'est jamais sur le bridge** : ``arp_ignore=1`` sur ``br-``, la + gateway en ``/32`` sur ``gw-``, l'adresse d'émission seule sur le bridge. Posée sur le + bridge, la gateway répondrait aux VM avec la MAC de l'hôte et l'anycast serait contourné sans + autre symptôme. +* **La route du subnet garde la gateway pour source** (``src``) : le netns parle à ses VM depuis + la gateway, leurs réponses reviennent à l'hôte local. Depuis l'adresse d'émission, partagée par + tous les hôtes, une réponse peut partir vers un autre hôte. * ``169.254.169.254`` est centralisé dans ``metadata.ServiceIP`` — ne pas le réécrire en dur. QEMU et VM diff --git a/docs/concepts/modes-reseau.rst b/docs/concepts/modes-reseau.rst index 6204e2c..265ef60 100644 --- a/docs/concepts/modes-reseau.rst +++ b/docs/concepts/modes-reseau.rst @@ -36,22 +36,85 @@ vxlan .. mermaid:: graph LR - VM --- TAP[tap] --- BR["br-<subnet>
interface_ip"] - BR --- VX["vxlan<vni>"] --- HBR["bridge host
(iface_type)"] --- UP[uplink] + VM --- TAP[tap] --- BR["br-<subnet>
adresse d'émission"] + GW["gw-<subnet>
gateway, MAC anycast"] -. macvlan .- BR + BR --- VETH["v-<subnet>-i / -e"] --- VX["vxlan-<vni>"] --- UP[uplink] Le subnet vit dans le netns du VPC. La VM n'est donc **pas joignable depuis l'host** sans route explicite — point à connaître avant de câbler un outil externe dessus. -Le bridge du subnet, qui porte ``interface_ip``, a une **MAC de gateway propre à l'hôte**, calculée -depuis son VTEP — l'IPv4 primaire du ``local_iface`` : ``02:03`` suivi des quatre octets de -l'adresse (VTEP ``192.168.14.12`` → ``02:03:c0:a8:0e:0c``). Unique dans le fabric, elle est la -même pour tous les subnets d'un hôte, chacun étant un domaine L2 distinct. Elle n'est posée qu'à la -création du subnet — un subnet créé avant garde la MAC choisie par le noyau jusqu'à sa recréation. +Adressage +~~~~~~~~~ -Une MAC de gateway **identique sur tous les hôtes** (anycast) a été essayée puis retirée : apprise -sur le veth du subnet, elle était annoncée en EVPN par chaque hôte et détectée en double ; et une -gateway ne pouvait plus joindre en L2 une VM d'un autre hôte, la réponse revenant à la gateway -locale de la VM. Le cache ARP d'une VM migrée à chaud est un sujet de la migration, pas du subnet. +L'agent calcule deux adresses à partir du ``cidr`` ; ``interface_ip`` n'est pas fourni par +l'appelant (refusé en 400) : + +* la **gateway**, avant-dernière adresse du préfixe (``.254`` en ``/24``), exposée comme + ``interface_ip`` ; +* l'**adresse d'émission**, juste avant (``.253``), exposée comme ``relay_ip``. + +Le ``cidr`` doit être sans bits d'hôte et faire au plus ``/29``. Une VM ne peut prendre ni l'une +ni l'autre de ces adresses, ni l'adresse de réseau, de broadcast ou la ``gateway`` explicite du +subnet (422). + +Gateway anycast +~~~~~~~~~~~~~~~ + +La gateway est portée par un macvlan ``gw-`` posé sur le bridge du netns. Sa MAC est +**identique sur tous les hôtes qui portent le subnet** : ``02:01:00`` suivi de la VNI sur 24 bits +(VNI ``2911`` → ``02:01:00:00:0b:5f``). Où qu'elle tourne, une VM résout sa gateway vers l'hôte +qui l'héberge, et une entrée ARP restée en cache reste valable si la VM change d'hôte. + +Le bridge ``br-`` garde une **MAC propre à l'hôte**, ``02:03`` suivi des quatre octets du +VTEP — l'IPv4 primaire du ``local_iface`` (``192.168.14.12`` → ``02:03:c0:a8:0e:0c``) — et porte +l'adresse d'émission : + +* le netns émet ses requêtes ARP depuis l'adresse d'émission (``arp_announce=2``) et le bridge ne + répond pas pour la gateway (``arp_ignore=1``). Quand un hôte relaie en L2 vers une VM d'un autre + hôte — trafic routé vers un subnet présent sur plusieurs hôtes, filet du ``/24`` d'un VPC + routé —, la VM répond à la MAC de cet hôte, sans que sa gateway change ; +* la route du subnet a la gateway pour source : le netns parle à **ses** VM depuis la gateway, et + leurs réponses reviennent à la MAC anycast, donc à l'hôte local ; +* le DHCP écoute sur ``gw-`` et s'annonce avec la gateway comme identifiant de serveur : + un renouvellement unicast reste servi par l'hôte de la VM. + +L'adresse d'émission est la même sur tous les hôtes : une VM qui reçoit la requête ARP d'un autre +hôte associe ``.253`` à la MAC de celui-ci. C'est sans effet — la VM ne parle jamais d'elle-même à +``.253`` et le netns lui parle depuis la gateway. Mesuré en lab (``s11-fenetre-arp``) : pendant +cette fenêtre, métadonnées, renouvellement DHCP et connexions depuis le netns passent sans perte. + +.. note:: + + Depuis le netns d'un hôte, une VM d'un **autre** hôte ne répond qu'à l'adresse d'émission + (``ping -I ``) : à la gateway, sa réponse repartirait vers son propre hôte. Le + trafic routé entre VM n'est pas concerné, il garde sa source. + +Confinement de la MAC anycast +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +La MAC anycast ne doit **jamais** sortir du netns : vue depuis le fabric, elle serait annoncée en +EVPN par chaque hôte, détectée en double, et déplacerait l'apprentissage des bridges. Trois +mécanismes la confinent : + +* ebtables, sur le veth du subnet : toute trame de **source** anycast est rejetée à l'entrée + (``nat PREROUTING``) et à la sortie (``FORWARD`` et ``OUTPUT``) ; +* une **entrée FDB locale** pour la MAC anycast dans le bridge du netns. Le macvlan ne la crée pas + lui-même : sans elle, toute trame d'une VM vers sa gateway est inondée vers le fabric et les + autres VM, et traitée par la gateway de chaque hôte ; +* les requêtes ARP vers la gateway ou l'adresse d'émission, et les réponses DHCP qui en viennent, + sont bloquées vers le veth, comme avant. + +IPv6 n'est pas désactivé sur le macvlan : ses trames (DAD, ND) sont arrêtées par le confinement. +Le watchdog contrôle le macvlan, sa MAC, les deux adresses et l'entrée FDB ; il ne relit pas les +règles ebtables. + +Subnets créés avant la gateway anycast +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Un subnet ``vxlan`` sans ``relay_ip`` garde le modèle précédent jusqu'à sa recréation : +``interface_ip`` choisie à la création, portée par le bridge, avec la MAC propre à l'hôte. Une VM +qui reçoit alors la requête ARP d'un autre hôte associe **sa gateway** à cet hôte pendant +quelques secondes (#57). bridge ------ @@ -81,7 +144,7 @@ Une route par défaut est **toujours** annoncée. Le champ ``default_route`` ne next-hop : ``default_route: false`` (défaut) - next-hop = ``interface_ip`` du subnet. + next-hop = ``interface_ip`` du subnet, la gateway calculée en ``vxlan``. ``default_route: true`` next-hop = le champ ``gateway`` s'il est fourni, sinon la gateway lue dans la table de routage @@ -100,7 +163,8 @@ Pourquoi la route ``/32`` vers le serveur de metadata est indispensable Elle paraît redondante avec la route par défaut. Elle ne l'est pas. La DNAT vers le serveur de metadata est posée dans le netns du VPC, en ``PREROUTING``. Le paquet -n'y est traité en L3 que si son next-hop est ``interface_ip``, portée par le bridge du netns. +n'y est traité en L3 que si son next-hop est ``interface_ip``, locale au netns — sur le macvlan de +la gateway en ``vxlan``, sur le bridge dans les autres modes. Avec un autre next-hop, la trame est commutée en **L2** sans traverser ``PREROUTING`` : le serveur de metadata devient injoignable et tout le provisionnement cloud-init échoue, silencieusement. diff --git a/docs/concepts/vpc-subnet-vm.rst b/docs/concepts/vpc-subnet-vm.rst index 8269149..0095c6b 100644 --- a/docs/concepts/vpc-subnet-vm.rst +++ b/docs/concepts/vpc-subnet-vm.rst @@ -6,7 +6,7 @@ Trois types de ressources, une hiérarchie stricte. .. mermaid:: graph TD - VPC["VPC
network namespace
cidr"] --> SN1["Subnet
bridge + VXLAN
interface_ip, cidr"] + VPC["VPC
network namespace
cidr"] --> SN1["Subnet
bridge + VXLAN
cidr, gateway"] VPC --> SN2["Subnet"] SN1 --> VM1["VM
QEMU/KVM"] SN1 --> VM2["VM"] @@ -57,8 +57,9 @@ configurée fait planter ``bgpd`` (FRR 10.7.1). Subnet ------ -Un subnet appartient à un VPC et pose, dans son netns, un bridge qui porte ``interface_ip`` — la -gateway vue par les VM. Il fournit aussi le DHCP — dnsmasq ou le serveur intégré selon +Un subnet appartient à un VPC et pose, dans son netns, un bridge et la gateway vue par les VM, +``interface_ip`` — calculée par l'agent et portée par un macvlan à MAC anycast en mode ``vxlan``, +fournie par l'appelant et portée par le bridge dans les autres modes. Il fournit aussi le DHCP — dnsmasq ou le serveur intégré selon ``dhcp.backend`` — et les routes annoncées aux guests. ``iface_type`` est une clé **logique** (``vms``, ``internet``, ``admin``…), traduite en nom de diff --git a/docs/exploitation/diagnostic.rst b/docs/exploitation/diagnostic.rst index b60200c..6c2a29f 100644 --- a/docs/exploitation/diagnostic.rst +++ b/docs/exploitation/diagnostic.rst @@ -63,6 +63,38 @@ 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 ne joint pas sa gateway (subnet ``vxlan``) +------------------------------------------------ + +La gateway d'un subnet ``vxlan`` est un macvlan ``gw-`` à MAC anycast +(:doc:`/concepts/modes-reseau`). Le watchdog contrôle sa présence, sa MAC, les adresses et l'entrée +FDB : ses notifications (``interface gw-…``, ``lacks the gateway address``, ``no local fdb +entry``…) disent déjà ce qui manque. À la main, dans le netns du VPC : + +.. code-block:: bash + + # macvlan actif, MAC 02:01:00:, gateway en /32 ; adresse d'émission seule sur le bridge + ip -n -br addr show gw- + ip -n -br addr show br- + + # entrée locale de la MAC anycast dans le bridge (« master br- permanent ») + ip netns exec bridge fdb show br br- | grep 02:01:00 + + # route du subnet émise depuis la gateway + ip -n -4 route show dev br- + + # confinement : source anycast rejetée sur le veth du subnet + ip netns exec ebtables -t nat -L PREROUTING + ip netns exec ebtables -L FORWARD + +Dans le guest, ``ip neigh show `` doit montrer la MAC ``02:01:00:``. Une autre MAC — +celle d'un hôte, ``02:03:…`` — signale un subnet de l'ancien modèle (sans ``relay_ip``) ou une +gateway posée sur le bridge. + +Depuis le netns d'un hôte, une VM d'un **autre** hôte ne répond qu'à l'adresse d'émission : +``ip netns exec ping -I ``. Un ping sans ``-I`` part de la gateway et la +réponse revient à l'hôte de la VM — ce n'est pas une panne. + La VM a une adresse mais cloud-init n'applique rien --------------------------------------------------- diff --git a/release_notes/0.2.0.md b/release_notes/0.2.0.md index 950937e..5b532bc 100644 --- a/release_notes/0.2.0.md +++ b/release_notes/0.2.0.md @@ -58,12 +58,25 @@ L3VNI, avec une configuration BGP pilotée par l'agent ; documentation du projet - 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`** +**Gateway anycast des subnets `vxlan` (#57)** -- Le bridge du subnet porte une **MAC propre à l'hôte**, `02:03:`, 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) +- 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-` à **MAC anycast** `02:01:00:`, + 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:`, 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-` ; 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** @@ -109,9 +122,8 @@ L3VNI, avec une configuration BGP pilotée par l'agent ; documentation du projet 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 +- **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) @@ -136,10 +148,16 @@ curl -O https://git.g3e.fr/syonad/two/raw/branch/main/scripts/deploy.sh bash ./deploy.sh -t 0.2.0 ``` -Aucune action n'est requise : sans `dhcp.backend` ni `bgp` dans `/etc/two/agent.yml`, le -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. +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