f-74: doc: vda racine, xvdX additionnels et /dev/xvdX par règle udev d'image, migration, notes de version #74

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
This commit is contained in:
GnomeZworc 2026-10-23 00:26:47 +02:00
commit d1b50d546c
Signed by: nicolas.boufideline
GPG key ID: 4406BBBF8845D632
8 changed files with 64 additions and 23 deletions

View file

@ -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-<dev>, scsi-0QEMU_QEMU_HARDDISK_<dev>).
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:

View file

@ -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``).

View file

@ -28,7 +28,7 @@ de sérialisation structurée.
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>
vm/<name>/disk/<dev> → <path> (une clé par disque : sda, vda, …)
vm/<name>/disk/<dev> → <path> (une clé par disque : vda, xvda, xvdb, …)
vm/<name>/memory → <int> (Mo)
vm/<name>/cpus → <int>
vm/<name>/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/<name>/disk/sdX`` en ``vm/<name>/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()``.

View file

@ -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 <https://git.g3e.fr/syonad/two/issues/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/…<dev>``.
**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/…<dev>``.
Ce qui est stocké, et où
------------------------

View file

@ -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 ``<dev>`` ; 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 ``<dev>`` ; 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
-----------

View file

@ -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

View file

@ -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

View file

@ -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 `<dev>`. 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/<name>/disk/sdX` deviennent `vm/<name>/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.