f-88: doc: IP flottante, interfaces nommées, notes 0.3.0 #88

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
This commit is contained in:
GnomeZworc 2026-10-29 21:56:40 +01:00
commit bcc495ae4a
Signed by: nicolas.boufideline
GPG key ID: 4406BBBF8845D632
8 changed files with 118 additions and 1 deletions

View file

@ -43,6 +43,12 @@ de sérialisation structurée.
nat-gateway/<name>/ip → <ip>/<préfixe> (IP de sortie, telle que fournie)
nat-gateway/<name>/gateway → <ip> (gateway des bordures)
floating-ip/<name>/state → creating | running | error | deleting | deleted
floating-ip/<name>/vm → <vm-name>
floating-ip/<name>/interface → <nom> (nom de l'interface de la VM ; l'IP privée y est lue)
floating-ip/<name>/ip → <ip>/<préfixe> (IP publique, telle que fournie)
floating-ip/<name>/gateway → <ip> (gateway des bordures)
Règles
------

View file

@ -14,3 +14,4 @@ fonctionnent entre eux. Le contrat HTTP correspondant est dans
metadata-cloud-init
dns-ntp
passerelle-nat
ip-flottante

View file

@ -0,0 +1,81 @@
IP flottante
============
Une IP flottante rend une interface de VM **joignable par une IP publique qu'elle ne porte pas**.
C'est une ressource de l'API de l'agent (``/floating-ips``), créée sur l'hyperviseur de la VM :
la VM garde son adresse privée, et le netns de son VPC traduit l'IP publique vers cette adresse,
dans les deux sens, sans suivi de connexion propre à la traduction.
.. code-block:: text
POST /floating-ips
{ "name": "fip-7", "vm": "vm-7", "interface": "nic-a1b2",
"ip": "203.0.113.20/24", "gateway": "203.0.113.1" }
``interface`` est le **nom** d'une interface de la VM (``name`` de l'interface, voir
:doc:`vpc-subnet-vm`), pas une interface Linux. L'IP publique, son préfixe et la gateway des
bordures sont fournis par l'appelant ; l'agent ne les vérifie pas. Une interface a au plus une IP
flottante, et une IP publique n'est portée que par une IP flottante de l'hôte. Le VPC n'a pas
besoin de ``l3vni``.
On attache et détache une IP flottante sans toucher à la VM. Le ``GET`` d'une VM l'affiche sur
l'interface concernée (``floating_ip`` : nom, IP, état), en lecture seule ; la suppression d'une
VM est refusée (409) tant qu'une IP flottante y est attachée.
Ce que l'agent pose
-------------------
Dans le netns du VPC de l'interface, sur l'hôte de la VM :
* un ``macvlan`` ``fip-<IP publique en hexadécimal>`` (``203.0.113.20`` → ``fip-cb007114``) sur
le bridge ``br-public`` du netns. Sa MAC est ``02:05`` suivi des quatre octets de l'IP publique
(``02:05:cb:00:71:14``) : unique dans l'infrastructure, la même sur tout hôte ;
* une entrée FDB locale de cette MAC, et ``arp_ignore=1``, ``arp_announce=2``, ``arp_notify=1``,
comme pour la :doc:`passerelle NAT <passerelle-nat>` ;
* deux chaînes dans la table nftables ``ip two`` :
* ``pre-fip-…``, en ``prerouting`` à la priorité ``raw`` : ce qui arrive par ``fip-…`` vers
l'IP publique est réécrit vers l'adresse privée, **avant** conntrack ;
* ``post-fip-…``, en ``postrouting`` : ce que la VM envoie par ``fip-…`` repart avec l'IP
publique pour source ;
conntrack ne voit que l'échange entre l'adresse privée et l'extérieur. Il n'y a pas de
``notrack`` : la redirection des métadonnées et le relais DNS et NTP, qui reposent sur
conntrack, restent servis à la VM. L'entrée est ouverte : c'est le but d'une IP flottante ;
* l'IP publique en ``/32`` sur ``fip-…`` : aucune route du segment public n'est ajoutée à la table
``main`` du netns ;
* une table de routage propre, numérotée par l'adresse privée lue comme un entier sur 32 bits
(``10.47.1.10`` → ``170852618``), qui porte la route du segment public par ``fip-…`` puis la
route par défaut vers la gateway des bordures ;
* deux règles de routage pour l'adresse privée :
* ``100: from <privée> to <cidr du VPC> lookup main`` : le trafic interne au VPC suit les routes
habituelles ;
* ``101: from <privée> lookup <table propre>`` : tout le reste sort par l'IP flottante, y compris
dans un VPC qui a une passerelle NAT, et sur l'hôte de celle-ci.
La table ``local`` passant avant ces règles, le trafic vers les adresses du netns (gateway,
métadonnées, DNS et NTP) n'est pas concerné.
Les règles nftables sont posées avant l'adresse et les routes : rien ne sort par ``fip-…`` sans
traduction. La suppression retire d'abord les règles de routage, puis les règles nftables,
l'entrée FDB et le ``macvlan``, dont les routes partent avec lui. Chaque étape tolère ce qui est
déjà absent : une suppression interrompue se relance depuis ``error``.
Le segment public n'apparaît pas dans ``main`` du fait de l'IP flottante : sinon, une VM sans IP
flottante du même netns pourrait sortir par ``fip-…`` sans traduction, et la réponse d'une VM à
IP flottante vers une adresse du segment (la bordure elle-même) sortirait par la passerelle NAT
avec son adresse privée.
Déplacer une IP flottante
-------------------------
Quand la VM change d'hôte, l'appelant supprime l'IP flottante sur l'ancien hôte, puis la crée sur
le nouveau. La MAC étant la même, le déplacement se réduit à un ARP gratuit et à la mobilité MAC
d'EVPN. Les connexions en cours sont perdues.
Limites
-------
* IPv4 seulement.
* Une VM qui joint l'IP flottante d'une autre VM passe par les bordures.

View file

@ -90,6 +90,9 @@ Si l'hôte de la passerelle tombe, ses routes restent annoncées jusqu'à l'expi
BGP vers les route reflectors (180 s), et le VPC n'a plus de sortie jusqu'à la création d'une
nouvelle passerelle.
Une VM qui a une :doc:`IP flottante <ip-flottante>` ne sort pas par la passerelle : elle sort par
son IP flottante, y compris sur l'hôte de la passerelle.
Limites
-------

View file

@ -112,7 +112,9 @@ Une VM est un processus QEMU/KVM raccordé à un ou plusieurs subnets par des ta
le nom de l'interface dans le guest. Chaque interface porte un ``name``, obligatoire et unique dans
la VM, choisi par l'appelant (``nic-a1b2`` par exemple) : c'est l'identifiant stable par lequel
l'API désigne une interface, son rang pouvant changer. Aucune interface Linux n'en tire son nom,
ni dans le guest ni sur l'hôte. Exactement une interface doit être ``primary`` : elle porte
ni dans le guest ni sur l'hôte. Une :doc:`IP flottante <ip-flottante>` désigne l'interface par ce
nom ; le ``GET`` de la VM l'affiche sur l'interface (``floating_ip``, en lecture seule, refusé à la
création), et la suppression de la VM est refusée (409) tant qu'elle est attachée. Exactement une interface doit être ``primary`` : elle porte
la route par défaut et le serveur de metadata. Tous les subnets d'une VM doivent appartenir au
**même VPC**.

View file

@ -400,6 +400,10 @@ Générée par ``test/e2e/run.sh --matrice`` à partir des en-têtes ; à régé
- passerelle NAT d'un VPC — macvlan ng-<id> sur le br-public du netns, MAC 02:04:00 + l3vni, SNAT vers l'IP de sortie (source vue à la sortie du netns), route par défaut en type 5 importée par un autre hôte, unreachable default jamais annoncée, rien n'entre sans connexion établie, refus 409, suppression propre, bascule vers un autre hôte par mobilité MAC
- hv1 hv2 hv3
- #42
* - ``47-ip-flottante``
- IP flottante d'une interface de VM — macvlan fip-<hex> sur le br-public du netns, MAC 02:05 + IP publique, NAT 1:1 sans état, routage par source (sortie par l'IP flottante, pas par la passerelle NAT du VPC), entrée neuve depuis le segment public, métadonnées servies, affichage sur la VM, refus 409, détachement, déplacement vers un autre hôte par mobilité MAC
- hv1 hv2 hv3
- #88
* - ``51-l3vni``
- routage inter-subnet entre hôtes par L3VNI (IRB symétrique) — VRF, RMAC, exports /24 et /32, RT-5 réfléchies, TTL, isolation par RT, unreachable default dans la VRF, démontage d'un VPC routé
- hv1 hv2

View file

@ -20,6 +20,8 @@ Exposées sur le port ``prometheus.port`` (9090 par défaut), alimentées par l'
- nombre de VM, par état
* - ``syonad_nat_gateways_total``
- nombre de passerelles NAT, par état
* - ``syonad_floating_ips_total``
- nombre d'IP flottantes, 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``

View file

@ -84,6 +84,24 @@
`syonad_nat_gateways_total` ; le watchdog attend la route par défaut d'une passerelle `running`
dans la VRF
**IP flottante (#88)**
- Nouvelle ressource `/floating-ips` (`POST`, `GET`, `DELETE`) : `name`, `vm`, `interface` (nom de
l'interface de la VM), `ip` (IP publique avec son préfixe) et `gateway`, fournis par l'appelant
et non vérifiés. Créée sur l'hôte de la VM, elle rend l'interface joignable par l'IP publique ;
la VM sort par elle, même dans un VPC qui a une passerelle NAT. 409 si la VM n'est pas `running`
sur l'hôte, si l'interface est inconnue ou a déjà une IP flottante, ou si l'IP publique est déjà
portée
- Dans le netns du VPC : `macvlan` `fip-<hex>` sur `br-public`, de MAC `02:05` + IP publique (la
même sur tout hôte), IP publique en `/32` ; NAT 1:1 sans état en nftables (table `ip two`),
sans `notrack` : métadonnées, DNS et NTP restent servis ; routage par source vers une table
propre, le trafic interne au VPC restant dans `main`
- Le `GET` d'une VM affiche l'IP flottante de chaque interface (`floating_ip`, en lecture seule) ;
la suppression d'une VM est refusée (409) tant qu'une IP flottante y est attachée. Nouvelle
métrique `syonad_floating_ips_total`
- Déplacer l'IP flottante avec la VM : la supprimer sur l'ancien hôte, la créer sur le nouveau. Les
connexions en cours sont perdues
## Correctifs
- **Chaque VRF de VPC porte une route `unreachable default` (#81).** Une recherche qui échouait