f-42: doc: passerelle NAT, routes par défaut du VPC, notes 0.3.0 #42

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
This commit is contained in:
GnomeZworc 2026-10-29 20:38:37 +01:00
commit 74e8c6220e
Signed by: nicolas.boufideline
GPG key ID: 4406BBBF8845D632
7 changed files with 143 additions and 4 deletions

View file

@ -37,6 +37,11 @@ de sérialisation structurée.
vm/<name>/sshkey → <pubkey> (optionnel)
vm/<name>/metadata/<document> → <contenu brut> (optionnel : user-data, vendor-data, …)
nat-gateway/<name>/state → creating | running | error | deleting | deleted
nat-gateway/<name>/vpc → <vpc-name> (une passerelle par VPC)
nat-gateway/<name>/ip → <ip>/<préfixe> (IP de sortie, telle que fournie)
nat-gateway/<name>/gateway → <ip> (gateway des bordures)
Règles
------

View file

@ -13,3 +13,4 @@ fonctionnent entre eux. Le contrat HTTP correspondant est dans
cycle-de-vie
metadata-cloud-init
dns-ntp
passerelle-nat

View file

@ -0,0 +1,98 @@
Passerelle NAT
==============
Une VM sans IP publique sort vers Internet par la **passerelle NAT de son VPC**. C'est une
ressource de l'API de l'agent (``/nat-gateways``), créée sur un seul hyperviseur, choisi par
l'appelant. Elle porte l'IP de sortie du VPC sur le segment public de l'hôte (``br-public``,
``vxlan-public``) et annonce une route par défaut de type 5 dans la VRF du VPC : toutes les VM du
VPC, sur tous les hyperviseurs, sortent par elle, avec cette IP pour source.
**L'autorisation Internet d'un VPC, c'est l'existence de sa passerelle** : le VPC ne porte aucun
champ pour cela. Le VPC doit avoir un ``l3vni``, et une seule passerelle existe par VPC. L'IP de
sortie, son préfixe et la gateway des bordures sont fournis par l'appelant ; l'agent ne les
vérifie pas.
Chemin d'un paquet
------------------
.. mermaid::
graph LR
V["VM sur l'hôte B"] --> NB["netns du VPC, hôte B<br/>route par défaut vers la VRF"]
NB --> RB["vrf-&lt;id&gt;, hôte B<br/>route par défaut de type 5"]
RB -->|"L3VNI"| RA["vrf-&lt;id&gt;, hôte A<br/>route par défaut vers 169.254.0.2"]
RA --> NA["netns du VPC, hôte A<br/>SNAT vers l'IP de sortie"]
NA -->|"ng-&lt;id&gt;, br-public, vxlan-public"| B["bordures"]
Le netns de chaque VPC routé envoie sa route par défaut vers la VRF. Sans passerelle, la route
``unreachable default`` de la VRF rejette ce trafic (voir :doc:`vpc-subnet-vm`) ; avec une
passerelle, la route par défaut de type 5 l'emporte, l'``unreachable`` ayant la métrique maximale.
Créer ou déplacer une passerelle ne demande donc rien aux autres hyperviseurs du VPC. Sur l'hôte
de la passerelle, les VM sortent directement par le netns, sans passer par la VRF.
Les réponses reviennent à l'IP de sortie : les bordures la résolvent vers la MAC de la
passerelle, le netns défait la traduction et renvoie le paquet vers la VM par la VRF.
Ce que l'agent pose
-------------------
Dans le netns du VPC ``vp-<id>``, sur l'hôte de la passerelle :
* un ``macvlan`` ``ng-<id>`` sur le bridge ``br-public`` du netns, déjà relié au bridge public de
l'hôte par ``vp-<id>-i`` / ``vp-<id>-e``. Sa MAC est **calculée** à partir du ``l3vni`` :
``02:04:00`` suivi du ``l3vni`` sur 24 bits (``4600`` → ``02:04:00:00:11:f8``). Elle est la
même quel que soit l'hôte : c'est ce qui permet de déplacer la passerelle ;
* une entrée FDB locale de cette MAC sur ``br-public`` : un ``macvlan`` n'en crée pas dans son
bridge parent, et sans elle les trames vers la passerelle seraient inondées au lieu de lui être
remises (même mécanisme que la MAC anycast des subnets ``vxlan``) ;
* ``arp_ignore=1``, ``arp_announce=2`` et ``arp_notify=1`` sur ``ng-<id>`` : la passerelle ne
répond à l'ARP que pour son IP de sortie, et annonce celle-ci par un ARP gratuit à sa mise en
route ;
* l'IP de sortie sur ``ng-<id>``, puis une route par défaut vers la gateway des bordures par
``ng-<id>``, à la place de celle vers la VRF ; le ``cidr`` du VPC reste routé vers la VRF ;
* trois chaînes dans la table nftables ``ip two`` du netns :
* ``snat-ng-<id>`` : ``snat`` vers l'IP de sortie de tout ce qui sort par ``ng-<id>`` ;
* ``fwd-ng-<id>`` et ``in-ng-<id>`` : rien n'entre par ``ng-<id>`` — ni vers les VM, ni vers le
netns lui-même (DNS et NTP, métadonnées) — hors réponse à une connexion établie
(``ct state established,related``). L'ARP n'est pas filtré ;
* en dernier, sur l'hôte, une route par défaut vers ``169.254.0.2`` dans la table de la VRF :
l'annonce n'est jamais faite avant que la traduction soit en place.
La suppression retire d'abord la route par défaut de la VRF, puis les règles nftables, remet la
route par défaut du netns vers la VRF, retire l'entrée FDB et le ``macvlan``. Chaque étape tolère
ce qui est déjà absent : une suppression interrompue se relance depuis ``error``. Le retrait de la
route de la VRF désigne sa gateway et son interface, de sorte que l'``unreachable default`` reste
en place.
Annonce de la route par défaut
------------------------------
Le route-map ``EXPORT-<id>`` de la VRF porte une entrée ``permit 15`` : ``0.0.0.0/0``, à
condition que son next-hop soit ``169.254.0.2`` (prefix-lists ``PL-<id>-default`` et
``PL-<id>-transit``). Sans cette condition, ``redistribute kernel`` exporterait aussi
l'``unreachable default`` de chaque hôte (constaté sur FRR 8.4, hors VRF), et tous les
hyperviseurs annonceraient une sortie qu'ils n'ont pas.
Ces entrées sont posées à la création du VPC et retirées à sa suppression ; seule la route du
noyau dépend de la passerelle.
Déplacer la passerelle
----------------------
L'agent ne détecte aucune panne et ne coordonne rien avec les autres hyperviseurs. Pour déplacer
la passerelle, l'appelant la supprime sur l'ancien hôte s'il répond, puis la crée sur le nouveau
avec la même IP. La MAC étant la même, la bascule se réduit à un ARP gratuit et à la mobilité MAC
d'EVPN. Les connexions en cours sont perdues.
Si l'hôte de la passerelle tombe, ses routes restent annoncées jusqu'à l'expiration des sessions
BGP vers les route reflectors (180 s), et le VPC n'a plus de sortie jusqu'à la création d'une
nouvelle passerelle.
Limites
-------
* Seuls les VPC créés par la 0.3.0 ou après envoient leur route par défaut vers la VRF et
exportent la route de la passerelle : un VPC plus ancien doit être recréé pour s'en servir.
* IPv4 seulement.

View file

@ -58,12 +58,15 @@ passe en ``error`` : ce VNI est déjà porté par ``vxlan-public``.
│ └── vxl3-<id> VXLAN du l3vni, VTEP = IPv4 primaire de default_interface
└── l3-<id>-o 169.254.0.1/30 ── l3-<id>-i 169.254.0.2/30, dans le netns du VPC
Dans le netns, le ``cidr`` du VPC est routé vers ``169.254.0.1`` ; le transit ``/30`` est le même
Dans le netns, le ``cidr`` du VPC et la route par défaut sont routés vers ``169.254.0.1`` : sans
passerelle NAT, l'``unreachable default`` de la VRF rejette ce qui n'est pas dans le VPC (voir
:doc:`passerelle-nat`) ; le transit ``/30`` est le même
sur tous les hyperviseurs et pour tous les VPC. L'agent active le forwarding IPv4 dans le netns,
et sur l'hôte sur ``brl3-<id>`` et ``l3-<id>-o``, les deux interfaces d'entrée de la VRF ; il ne
touche pas au réglage global, que ``bootstrap_kvm.sh`` met déjà à 1. FRR reçoit la VRF, son ``vni``, une instance
``router bgp <asn> vrf vrf-<id>`` avec RD ``<VTEP>:<l3vni>`` et RT ``<asn>:<l3vni>``, et
l'export des routes du ``cidr`` présentes dans la VRF.
l'export des routes du ``cidr`` présentes dans la VRF, et de la route par défaut de la passerelle
NAT.
La table de la VRF reçoit, juste après sa création, une route ``unreachable default`` de métrique
maximale (``4278198272``, valeur recommandée par la documentation VRF du noyau). Sans elle, une
@ -71,7 +74,8 @@ recherche qui échoue dans la VRF continue dans les règles suivantes, donc dans
de l'hôte : un paquet d'un locataire vers une adresse inconnue de la VRF sortirait par l'underlay,
avec ``169.254.0.2`` pour source (mesuré, `#81 <https://git.g3e.fr/syonad/two/issues/81>`_). La
métrique maximale laisse passer avant elle toute route réelle de la VRF. Cette route n'est pas
annoncée en EVPN : le route-map de la VRF n'exporte que le ``cidr`` du VPC. Elle n'est liée à
annoncée en EVPN : le route-map de la VRF n'exporte que le ``cidr`` du VPC, et la route par
défaut seulement quand son next-hop est ``169.254.0.2``, celle d'une passerelle NAT. Elle n'est liée à
aucune interface et ne disparaît pas avec la VRF : la suppression la retire explicitement. IPv4
seulement.

View file

@ -396,6 +396,10 @@ Générée par ``test/e2e/run.sh --matrice`` à partir des en-têtes ; à régé
- segment public de l'hôte — vxlan-public (VNI 1) posé par le bootstrap sur br-public, VNI annoncé en EVPN et vu par les bordures, gateway anycast des bordures installée vers une seule bordure, gateway et destination de test joignables sans doublon, L2 entre hyperviseurs, veth des VPC sur le bridge public, watchdog
- hv1 hv2 hv3
- #87
* - ``46-passerelle-nat``
- 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
* - ``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

@ -18,6 +18,8 @@ Exposées sur le port ``prometheus.port`` (9090 par défaut), alimentées par l'
- nombre de subnets, par état
* - ``syonad_vms_total``
- nombre de VM, par état
* - ``syonad_nat_gateways_total``
- nombre de passerelles NAT, 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``
@ -63,7 +65,8 @@ Avec une section ``bgp`` dans la configuration, il contrôle aussi le plan de co
par une version antérieure à la 0.3.0 ne l'a pas : il est signalé à chaque tick jusqu'à sa
recréation, l'agent ne la pose pas au démarrage.
* **Réconciliation des routes exportées** dans la VRF : chaque ``/24`` de subnet ``vxlan`` et chaque
``/32`` d'interface de VM ``running`` doit être exporté ; à l'inverse, une route exportée dont
``/32`` d'interface de VM ``running`` doit être exporté, ainsi que la route par défaut quand le
VPC a une passerelle NAT ``running`` sur l'hôte (voir :doc:`../concepts/passerelle-nat`) ; à l'inverse, une route exportée dont
le propriétaire n'existe plus — ni ``running``, ni en ``creating``, ``deleting`` ou ``error`` —
est signalée comme un **trou noir** : l'annonce attire du trafic que plus rien ne reçoit.

View file

@ -57,6 +57,26 @@
(`br-public` par défaut, jamais `default_interface`), au lieu d'un nom en dur
- Le watchdog signale un bridge public absent, éteint ou sans port VXLAN
**Passerelle NAT des VPC (#42)**
- Nouvelle ressource `/nat-gateways` (`POST`, `GET`, `DELETE`) : `name`, `vpc`, `ip` (IP de
sortie avec son préfixe) et `gateway` (gateway des bordures), fournis par l'appelant et non
vérifiés. Créée sur un seul hyperviseur, elle donne une sortie Internet à toutes les VM du VPC,
sur tous les hyperviseurs, avec l'IP de sortie pour source. Une passerelle par VPC ; le VPC
doit être `running` sur l'hôte et avoir un `l3vni` (409 sinon)
- Dans le netns du VPC : `macvlan` `ng-<id>` sur le bridge `br-public` du netns, de MAC
`02:04:00` + `l3vni` (la même sur tout hôte), SNAT en nftables (table `ip two`) ; rien n'entre
par la passerelle hors réponse à une connexion établie. La route par défaut est annoncée en
type 5 dans la VRF du VPC
- Le netns de chaque VPC routé envoie désormais sa route par défaut vers la VRF ; sans passerelle,
l'`unreachable default` de #81 la rejette. Le route-map de la VRF exporte `0.0.0.0/0` seulement
si son next-hop est `169.254.0.2`, ce qui écarte l'`unreachable default`
- Déplacer la passerelle : la supprimer sur l'ancien hôte s'il répond, la créer sur le nouveau
avec la même IP. Les connexions en cours sont perdues
- La suppression d'un VPC est refusée (409) tant qu'il a une passerelle. Nouvelle métrique
`syonad_nat_gateways_total` ; le watchdog attend la route par défaut d'une passerelle `running`
dans la VRF
## Correctifs
- **Chaque VRF de VPC porte une route `unreachable default` (#81).** Une recherche qui échouait
@ -119,6 +139,10 @@
la fuite vers l'underlay décrite plus haut reste possible. Pour la fermer sans recréer le VPC,
la poser à la main sur chaque hyperviseur, la table étant le `l3vni` du VPC :
`ip route replace unreachable default metric 4278198272 table <l3vni>`
- **Passerelle NAT (#42) : seuls les VPC créés par la 0.3.0 peuvent s'en servir.** Les VPC
routés existants n'envoient pas leur route par défaut vers la VRF et leur route-map n'exporte
pas celle de la passerelle ; l'agent ne les reprend pas au démarrage. Recréer le VPC avant de
lui donner une passerelle
- **La section `dispatcher` n'est plus lue** : restée dans `/etc/two/agent.yml`, elle est ignorée,
et les valeurs par défaut de `times` s'appliquent. Une valeur personnalisée de
`dispatcher.timeout_seconds` est à reporter dans `times.timeout_vms_stop` (et dans les délais