From 62e73e997bbdd1edc935c8fb57b78ad3cc977d4f Mon Sep 17 00:00:00 2001 From: GnomeZworc Date: Mon, 19 Oct 2026 21:28:46 +0200 Subject: [PATCH] =?UTF-8?q?f-62:=20doc:=20MAC=20fournie=20=C3=A0=20la=20cr?= =?UTF-8?q?=C3=A9ation,=20sch=C3=A9ma=20des=20cl=C3=A9s,=20migration,=20no?= =?UTF-8?q?tes=20de=20version=200.2.0=20#62?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: GnomeZworc --- README.md | 2 +- docs/architecture/stockage.rst | 9 ++++++++- docs/concepts/vpc-subnet-vm.rst | 6 +++++- docs/demarrage/premier-vpc.rst | 6 +++++- release_notes/0.2.0.md | 13 ++++++++++++- 5 files changed, 31 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9382e13..538b2ae 100644 --- a/README.md +++ b/README.md @@ -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"}]}' ``` diff --git a/docs/architecture/stockage.rst b/docs/architecture/stockage.rst index fcea89b..c8c9af4 100644 --- a/docs/architecture/stockage.rst +++ b/docs/architecture/stockage.rst @@ -20,11 +20,11 @@ de sérialisation structurée. subnet//local_iface → subnet//default_route → "true" | "false" subnet//gateway → (optionnel) - subnet//dhcp/ → vm//state → creating | running | error | deleting | deleted vm//nic//subnet → (une interface par index, ordre du tableau interfaces) vm//nic//ip → + vm//nic//mac → (fournie par l'appelant, conservée telle quelle) vm//nic//primary → "true" (exactement une interface ; absent sur les autres) vm//nic//tap_id → (alloué au premier démarrage, puis conservé) vm//metadata_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//dhcp/``. Au démarrage, l'agent +recopie la MAC de chaque interface existante dans ``vm//nic//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()``. diff --git a/docs/concepts/vpc-subnet-vm.rst b/docs/concepts/vpc-subnet-vm.rst index 0095c6b..8dcf2b7 100644 --- a/docs/concepts/vpc-subnet-vm.rst +++ b/docs/concepts/vpc-subnet-vm.rst @@ -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//subnet``), pas le VPC ni le bridge ni la gateway : ces valeurs sont lues +subnet (``vm//nic//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`. diff --git a/docs/demarrage/premier-vpc.rst b/docs/demarrage/premier-vpc.rst index 2a1f96d..562978f 100644 --- a/docs/demarrage/premier-vpc.rst +++ b/docs/demarrage/premier-vpc.rst @@ -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 diff --git a/release_notes/0.2.0.md b/release_notes/0.2.0.md index e2d0580..001f589 100644 --- a/release_notes/0.2.0.md +++ b/release_notes/0.2.0.md @@ -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//dhcp/`, 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.