f-62: doc: MAC fournie à la création, schéma des clés, migration, notes de version 0.2.0 #62

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
This commit is contained in:
GnomeZworc 2026-10-19 21:28:46 +02:00
commit 62e73e997b
Signed by: nicolas.boufideline
GPG key ID: 4406BBBF8845D632
5 changed files with 31 additions and 5 deletions

View file

@ -57,7 +57,7 @@ curl -X POST http://127.0.0.1:8080/vms \
-d '{"name": "i-web", "memory": 2048, "cpus": 2,
"metadata": {"sshkey": "ssh-ed25519 AAAA…",
"user_data": "'"$(base64 -w0 < user-data.yml)"'"},
"interfaces": [{"subnet": "sn-000001", "ip": "10.1.1.2", "primary": true}],
"interfaces": [{"subnet": "sn-000001", "ip": "10.1.1.2", "mac": "52:54:00:01:01:02", "primary": true}],
"storage": [{"path": "/data/disks/vms/i-web.qcow2", "dev": "vda"}]}'
```

View file

@ -20,11 +20,11 @@ de sérialisation structurée.
subnet/<name>/local_iface → <bridge-name>
subnet/<name>/default_route → "true" | "false"
subnet/<name>/gateway → <ip> (optionnel)
subnet/<name>/dhcp/<ip> → <mac>
vm/<name>/state → creating | running | error | deleting | deleted
vm/<name>/nic/<i>/subnet → <subnet-name> (une interface par index, ordre du tableau interfaces)
vm/<name>/nic/<i>/ip → <ip>
vm/<name>/nic/<i>/mac → <mac> (fournie par l'appelant, conservée telle quelle)
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>
@ -48,6 +48,13 @@ lus depuis le subnet, leur source canonique. De même, la L3VNI d'un VPC n'est s
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.
**Ancienne table des MAC.** Jusqu'en 0.1.0, la MAC d'une interface était dérivée du rang de son IP
et préchargée pour tout le ``cidr`` sous ``subnet/<name>/dhcp/<ip>``. Au démarrage, l'agent
recopie la MAC de chaque interface existante dans ``vm/<name>/nic/<i>/mac``, puis supprime ces
clés. Les VM ``deleted`` sont ignorées. Une interface dont la MAC est introuvable fait échouer le
démarrage en la nommant, et la table reste en place tant que toutes les interfaces ne sont pas
migrées.
**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
écrit que par ``Dispatcher.Dispatch``, via ``cmd.Key()``.

View file

@ -84,6 +84,10 @@ le nom de l'interface dans le guest. Exactement une interface doit être ``prima
la route par défaut et le serveur de metadata. Tous les subnets d'une VM doivent appartenir au
**même VPC**.
**MAC.** Chaque interface porte la MAC choisie par l'appelant, comme son IP. L'agent la donne
telle quelle à QEMU et à la réservation DHCP, sans en vérifier le format ni l'unicité : c'est à
l'appelant de garantir qu'elle est unique sur le segment L2.
**Routes.** Dans un VPC routé par ``l3vni``, chaque interface sur un subnet ``vxlan`` est annoncée
en ``/32`` dans la VRF du VPC une fois QEMU démarré, juste avant le passage en ``running``. À la
suppression, ces ``/32`` sont retirés **avant** l'arrêt de QEMU. Comme un subnet ne peut être
@ -98,7 +102,7 @@ Ce qui est stocké, et où
------------------------
Une ressource ne porte en base que ce qui lui est propre. Une VM stocke le **lien** vers son
subnet (``vm/<name>/subnet``), pas le VPC ni le bridge ni la gateway : ces valeurs sont lues
subnet (``vm/<name>/nic/<i>/subnet``), pas le VPC ni le bridge ni la gateway : ces valeurs sont lues
depuis le subnet, leur source canonique. Le schéma complet des clés est dans
:doc:`/architecture/stockage`.

View file

@ -93,7 +93,7 @@ Là encore, attendez ``running`` :
"uefi": true,
"metadata": {"sshkey": "ssh-ed25519 AAAA…",
"user_data": "'"$(base64 < user-data.yml | tr -d '\n')"'"},
"interfaces": [{"subnet": "sn-000001", "ip": "10.1.1.2", "primary": true}],
"interfaces": [{"subnet": "sn-000001", "ip": "10.1.1.2", "mac": "52:54:00:01:01:02", "primary": true}],
"storage": [{"path": "/var/lib/two/volumes/i-web.qcow2", "dev": "vda"}]}'
Quatre points qui coûtent du temps quand on les découvre en production :
@ -106,6 +106,10 @@ Quatre points qui coûtent du temps quand on les découvre en production :
Le champ attend la valeur de la clé ``passwd`` de cloud-config (``$6$…``). Sans ``password``
ni ``sshkey``, aucun compte n'est créé.
Chaque interface a sa ``mac``
Choisie par l'appelant, obligatoire (400 sinon) et jamais vérifiée : deux interfaces sur le
même segment L2 doivent avoir des MAC distinctes.
Exactement une interface est ``primary``
Elle porte la route par défaut et le serveur de metadata. L'ordre du tableau détermine le
slot PCI (``0x03 + index``), donc le nom de l'interface dans le guest. Tous les subnets d'une

View file

@ -78,6 +78,15 @@ L3VNI, avec une configuration BGP pilotée par l'agent ; documentation du projet
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
**MAC des VM fournie à la création (#62)**
- Champ `mac` obligatoire par interface dans `POST /vms`, rendu par `GET /vms/{name}`. Il est
passé tel quel à QEMU et à la réservation DHCP ; son format et son unicité relèvent de l'appelant
- Fin de la table `subnet/<name>/dhcp/<ip>`, qui préchargeait une MAC par adresse du `cidr` : la
MAC dérivée du rang de l'IP donnait la même MAC à deux interfaces d'une VM de même rang dans
leurs subnets (VM injoignable), et n'était pas tenable en IPv6
- Migration au démarrage : les VM existantes gardent leur MAC, recopiée sur chaque interface
**Exploitation**
- Le watchdog contrôle aussi, avec une section `bgp` : les sessions vers les route reflectors ;
@ -155,12 +164,14 @@ 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 :
trois 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
- **chaque interface d'une VM doit porter sa `mac`** (400 sinon) : l'appelant la choisit et en
garantit l'unicité. Les VM existantes gardent la leur, recopiée au premier démarrage de l'agent
Les subnets `vxlan` existants gardent leur adressage et le modèle précédent (gateway sur le
bridge) jusqu'à leur recréation.