From d1b50d546c6ecc49eafd840b5baf0dc57925de62 Mon Sep 17 00:00:00 2001 From: GnomeZworc Date: Fri, 23 Oct 2026 00:26:47 +0200 Subject: [PATCH] =?UTF-8?q?f-74:=20doc:=20vda=20racine,=20xvdX=20additionn?= =?UTF-8?q?els=20et=20/dev/xvdX=20par=20r=C3=A8gle=20udev=20d'image,=20mig?= =?UTF-8?q?ration,=20notes=20de=20version=20#74?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: GnomeZworc --- api/agent.yaml | 14 ++++++++------ docs/architecture/contraintes.rst | 3 ++- docs/architecture/stockage.rst | 8 +++++++- docs/concepts/vpc-subnet-vm.rst | 11 ++++++----- docs/demarrage/premier-vpc.rst | 15 ++++++++------- docs/deploiement/image-qcow2.rst | 15 +++++++++++++++ docs/developpement/lab.rst | 4 ++-- release_notes/0.2.0.md | 17 ++++++++++++++++- 8 files changed, 64 insertions(+), 23 deletions(-) diff --git a/api/agent.yaml b/api/agent.yaml index 26b223e..03aad15 100644 --- a/api/agent.yaml +++ b/api/agent.yaml @@ -567,12 +567,14 @@ components: dev: type: string description: >- - Disk slot: vda is the virtio-blk system disk (one at most), sdX - is SCSI target X (a → 0). Not a guaranteed name inside the VM: - the guest kernel names SCSI disks in detection order. The disk - serial is set to dev, so the guest finds it under - /dev/disk/by-id/ (virtio-, scsi-0QEMU_QEMU_HARDDISK_). - pattern: '^[sv]d[a-z]$' + vda is the virtio-blk root disk, seen as /dev/vda and booted + first. xvdX is an additional disk on SCSI target X (xvda → 0), + seen by the guest kernel as some /dev/sdY in detection order. The + disk serial is set to dev: an image that follows the two image + requirements links it to /dev/xvdX, and udev always exposes it as + /dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_xvdX (virtio-vda for the + root disk). Anything else → 400; sdX is no longer accepted. + pattern: '^(vda|xvd[a-z])$' example: vda VM: diff --git a/docs/architecture/contraintes.rst b/docs/architecture/contraintes.rst index c83fec6..42e8de2 100644 --- a/docs/architecture/contraintes.rst +++ b/docs/architecture/contraintes.rst @@ -39,7 +39,8 @@ Réseau QEMU et VM ---------- -* **Un seul disque ``vdX`` par VM** ; les disques additionnels passent par le SCSI (``sdX``). La +* **Un seul disque virtio, ``vda``, le disque racine** ; les disques additionnels passent par le SCSI + (``xvdX``, cible X). La carte PCI en dépend : NIC en ``0x03``, contrôleur SCSI en ``0x1e``, virtio-blk en ``0x1f``. * ``bus=pci.0`` est explicite sur les trois ``-device`` : un passage de la machine en **q35** casserait le démarrage (``Bus 'pci.0' not found``). diff --git a/docs/architecture/stockage.rst b/docs/architecture/stockage.rst index c8c9af4..431b92b 100644 --- a/docs/architecture/stockage.rst +++ b/docs/architecture/stockage.rst @@ -28,7 +28,7 @@ de sérialisation structurée. 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 → - vm//disk/ → (une clé par disque : sda, vda, …) + vm//disk/ → (une clé par disque : vda, xvda, xvdb, …) vm//memory → (Mo) vm//cpus → vm//uefi → "true" (absent si SeaBIOS) @@ -55,6 +55,12 @@ clés. Les VM ``deleted`` sont ignorées. Une interface dont la MAC est introuva démarrage en la nommant, et la table reste en place tant que toutes les interfaces ne sont pas migrées. +**Anciens noms de disques.** Jusqu'en 0.1.0, les disques additionnels s'appelaient ``sdX``. Au +démarrage, l'agent renomme chaque clé ``vm//disk/sdX`` en ``vm//disk/xvdX`` (même +lettre, même cible SCSI). Si ``xvdX`` existe déjà avec un autre chemin, le démarrage échoue en +nommant la clé. Le numéro de série du disque, et donc son lien ``by-id``, prend le nouveau nom au +prochain lancement de la VM. + **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 212225e..ca9ebcc 100644 --- a/docs/concepts/vpc-subnet-vm.rst +++ b/docs/concepts/vpc-subnet-vm.rst @@ -94,11 +94,12 @@ suppression, ces ``/32`` sont retirés **avant** l'arrêt de QEMU. Comme un subn supprimé tant qu'une VM l'utilise, le ``/32`` d'une VM est toujours retiré avant le ``/24`` de son subnet — l'ordre qui évite le trou noir de `#41 `_. -**Stockage.** Un seul disque ``vdX`` (virtio-blk) par VM ; les disques supplémentaires passent -par le contrôleur SCSI (``sdX``). Cette contrainte vient de la carte PCI figée — voir -:doc:`/architecture/contraintes`. ``dev`` fixe l'emplacement du disque (cible SCSI, slot PCI) -et son numéro de série, pas son nom dans le guest : le disque se retrouve par -``/dev/disk/by-id/…``. +**Stockage.** Un seul disque virtio par VM, ``vda``, le disque racine ; les disques +supplémentaires passent par le contrôleur SCSI (``xvdX``, cible X). Cette contrainte vient de la +carte PCI figée — voir :doc:`/architecture/contraintes`. ``dev`` fixe l'emplacement du disque +(cible SCSI, slot PCI) et son numéro de série, pas le nom que lui donne le noyau du guest +(``/dev/sdY``, dans l'ordre de détection) : le disque se retrouve par ``/dev/xvdX`` dans une +image conforme, et toujours par ``/dev/disk/by-id/…``. Ce qui est stocké, et où ------------------------ diff --git a/docs/demarrage/premier-vpc.rst b/docs/demarrage/premier-vpc.rst index 3d3b2de..567b5bc 100644 --- a/docs/demarrage/premier-vpc.rst +++ b/docs/demarrage/premier-vpc.rst @@ -115,15 +115,16 @@ Exactement une interface est ``primary`` slot PCI (``0x03 + index``), donc le nom de l'interface dans le guest. Tous les subnets d'une VM doivent appartenir au même VPC. -Un seul disque ``vdX`` - Les disques supplémentaires passent par ``sdX``. La carte PCI en dépend — voir +``vda`` pour la racine, ``xvdX`` pour les autres disques + ``vda`` est le disque racine, virtio, démarré en premier. Les disques supplémentaires sont des + ``xvdX`` (``xvda`` = cible SCSI 0) ; ``sdX`` est refusé (400). La carte PCI en dépend — voir :doc:`/architecture/contraintes`. -``dev`` désigne un emplacement, pas un nom dans le guest - ``sdb`` est la cible SCSI 1, mais le noyau du guest nomme les disques SCSI dans l'ordre de - détection : ``/dev/sdb`` peut être un autre disque. L'agent donne à chaque disque le numéro - de série ```` ; le nom stable est sous ``/dev/disk/by-id/`` : - ``scsi-0QEMU_QEMU_HARDDISK_sdb``, ``virtio-vda``. +``/dev/xvdX`` dans le guest, jamais ``/dev/sdX`` + Le noyau du guest nomme les disques SCSI ``sdX`` dans l'ordre de détection, qui change d'un + démarrage à l'autre. L'agent donne à chaque disque le numéro de série ```` ; une image + conforme (:doc:`/deploiement/image-qcow2`) en fait le lien ``/dev/xvdX``. Sans cette règle, + le nom stable reste ``/dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_xvdX``. 4. Vérifier ----------- diff --git a/docs/deploiement/image-qcow2.rst b/docs/deploiement/image-qcow2.rst index a8e0488..5922a47 100644 --- a/docs/deploiement/image-qcow2.rst +++ b/docs/deploiement/image-qcow2.rst @@ -284,6 +284,21 @@ interface (``10-netplan-*``). Sur une image démarrée avec ``net.ifnames=0``, v l'image Rocky de cette page, n'est pas encore vérifié. Sans lui, une VM à plusieurs interfaces n'a de bail que sur la première. +**Noms stables des disques additionnels** + +.. code-block:: bash + + cat << 'ENDFILE' > /mnt/etc/udev/rules.d/90-two-xvd.rules + SUBSYSTEM=="block", ENV{DEVTYPE}=="disk", ENV{ID_SERIAL_SHORT}=="xvd[a-z]", SYMLINK+="$env{ID_SERIAL_SHORT}" + SUBSYSTEM=="block", ENV{DEVTYPE}=="partition", ENV{ID_SERIAL_SHORT}=="xvd[a-z]", SYMLINK+="$env{ID_SERIAL_SHORT}%n" + ENDFILE + +L'agent donne à chaque disque additionnel le numéro de série ``xvdX`` déclaré dans l'API ; ces +règles en font ``/dev/xvdX`` (et ``/dev/xvdXN`` pour ses partitions). Le noyau, lui, nomme les +disques SCSI ``/dev/sdY`` dans l'ordre de détection, qui change d'un démarrage à l'autre : une +``fstab`` ou un script de la VM doit viser ``/dev/xvdX``, jamais ``/dev/sdY``. Le disque racine +reste ``/dev/vda``. + **Services et durcissement** .. code-block:: bash diff --git a/docs/developpement/lab.rst b/docs/developpement/lab.rst index a3972bb..659ea24 100644 --- a/docs/developpement/lab.rst +++ b/docs/developpement/lab.rst @@ -320,7 +320,7 @@ Générée par ``test/e2e/run.sh --matrice`` à partir des en-têtes ; à régé - hv1 - #33, #62, #73 * - ``26-multi-disque`` - - VM à plusieurs disques — virtio (vdX) et SCSI (sdX), tailles et bus vus par la VM, liens ``by-id`` par numéro de série, démarrage sur vda + - VM à plusieurs disques — racine virtio (vda) et SCSI (xvdX), tailles et bus vus par la VM, liens ``/dev/xvdX`` et ``by-id`` par numéro de série, démarrage sur vda - hv1 - #32, #74 * - ``27-reboot`` @@ -412,7 +412,7 @@ Hypothèses vérifiées en lab, à garder en tête en écrivant un test : * systemd-networkd **ne réécrit pas** un bail renouvelé à l'identique : un renouvellement se vérifie par le DHCPACK dans le journal du serveur (``lease_renewed``), pas par le fichier de bail ; -* l'agent n'accepte **qu'un seul disque virtio** (le disque système) ; les autres sont des ``sdX`` ; +* l'agent n'accepte **qu'un seul disque virtio** (le disque racine, ``vda``) ; les autres sont des ``xvdX`` ; * sur Debian 12, ``ebtables -L`` (nft) garde les zéros de tête des MAC ; * ``interface_ip`` est posée en ``/32`` sur le bridge du netns en mode ``bridge`` ; * depuis le netns d'un hôte, une VM d'un autre hôte ne répond pas : la réponse repart vers la diff --git a/release_notes/0.2.0.md b/release_notes/0.2.0.md index 001f589..77c0798 100644 --- a/release_notes/0.2.0.md +++ b/release_notes/0.2.0.md @@ -87,6 +87,18 @@ L3VNI, avec une configuration BGP pilotée par l'agent ; documentation du projet 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 +**Disques : `vda` pour la racine, `xvdX` pour les autres (#74)** + +- `dev` accepte désormais `vda`, le disque racine virtio, et `xvda` à `xvdz` pour les disques + additionnels, sur la cible SCSI de même rang (`xvda` → 0). Toute autre valeur est refusée (400), + `sdX` compris +- Chaque disque reçoit le numéro de série ``. Le noyau de l'invité nomme les disques SCSI + `/dev/sdY` dans l'ordre de détection, qui change d'un démarrage à l'autre (mesuré en lab : `sda` + et `sdb` inversés 4 démarrages sur 6). Le nom stable est `/dev/xvdX`, créé par une règle udev + de l'image (exigence décrite dans la documentation de construction d'image), et toujours + `/dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_xvdX` +- Migration au démarrage : les clés `vm//disk/sdX` deviennent `vm//disk/xvdX` + **Exploitation** - Le watchdog contrôle aussi, avec une section `bgp` : les sessions vers les route reflectors ; @@ -164,7 +176,7 @@ 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, à -trois exceptions près, qui touchent les appelants de l'API : +quatre 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 @@ -172,6 +184,9 @@ trois exceptions près, qui touchent les appelants de l'API : - **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 disques additionnels s'appellent `xvdX`** : `sdX` est refusé (400). Les VM existantes sont + migrées ; leurs disques prennent le numéro de série `xvdX` au prochain lancement, et une image + qui les montait par `/dev/sdY` doit passer à `/dev/xvdX` Les subnets `vxlan` existants gardent leur adressage et le modèle précédent (gateway sur le bridge) jusqu'à leur recréation.