From edfd24f92be785f8b42fe4ac9b76df9829a37a2d Mon Sep 17 00:00:00 2001 From: GnomeZworc Date: Sun, 25 Oct 2026 12:42:20 +0100 Subject: [PATCH] f-79: doc: section times, suppressions en cascade, notes 0.3.0 #79 Signed-off-by: GnomeZworc --- docs/architecture/contraintes.rst | 3 +- docs/concepts/cycle-de-vie.rst | 5 ++- docs/demarrage/premier-vpc.rst | 2 +- docs/developpement/lab.rst | 6 +-- docs/exploitation/api-agent/asynchronisme.rst | 16 ++++--- docs/exploitation/configuration.rst | 44 +++++++++++++++---- release_notes/0.3.0.md | 32 ++++++++++++++ 7 files changed, 88 insertions(+), 20 deletions(-) create mode 100644 release_notes/0.3.0.md diff --git a/docs/architecture/contraintes.rst b/docs/architecture/contraintes.rst index 5686cee..6f90eee 100644 --- a/docs/architecture/contraintes.rst +++ b/docs/architecture/contraintes.rst @@ -43,7 +43,8 @@ QEMU et VM exécuté par le processus appelant et hérite du netns posé par ``netns.Call``. Une unit transitoire, forkée par PID 1, démarrerait dans le netns racine et ne verrait pas le tap. * L'arrêt d'une VM ne touche **jamais** aux fichiers disque. En revanche, un ``quit`` brutal est - envoyé à l'expiration de ``dispatcher.timeout_seconds``. + envoyé à l'expiration de ``times.timeout_vms_stop``. ``system_powerdown`` est renvoyé toutes les + ``times.next_vms_shutdown`` : un appui ACPI arrivé avant que l'invité sache le traiter est perdu. Arrêt de l'agent ---------------- diff --git a/docs/concepts/cycle-de-vie.rst b/docs/concepts/cycle-de-vie.rst index bf41484..adcc57b 100644 --- a/docs/concepts/cycle-de-vie.rst +++ b/docs/concepts/cycle-de-vie.rst @@ -40,7 +40,10 @@ Suppression Elle n'est autorisée que depuis ``running`` ou ``error`` — sinon **409**. Depuis ``error``, elle est **best-effort** : les ressources système peuvent n'avoir été créées que partiellement. -Un VPC ne peut être supprimé qu'une fois tous ses subnets supprimés. +Un VPC ne peut être supprimé qu'une fois tous ses subnets supprimés ou en ``deleting``, un subnet +qu'une fois toutes ses VM supprimées ou en ``deleting``. Les enfants encore en ``deleting`` sont +attendus (``times.timeout_vpc_stop``, ``times.timeout_subnet_stop``) ; si l'un d'eux passe en +``error``, la suppression du parent échoue, et le parent passe en ``error`` à son tour. Pas de rollback --------------- diff --git a/docs/demarrage/premier-vpc.rst b/docs/demarrage/premier-vpc.rst index 534dd55..b55693f 100644 --- a/docs/demarrage/premier-vpc.rst +++ b/docs/demarrage/premier-vpc.rst @@ -48,7 +48,7 @@ La réponse est un **202** : la création est acceptée, pas terminée. Un subnet peut être demandé dès maintenant : il est accepté tant que le VPC est en ``creating`` ou ``running``, et sa création attend que le VPC soit ``running``, dans la limite de -``dispatcher.timeout_seconds``. Il n'est refusé en **422** que si le VPC est absent, en ``error`` +``times.timeout_subnet_start``. Il n'est refusé en **422** que si le VPC est absent, en ``error`` ou en ``deleting``. Le modèle d'attente est décrit dans :doc:`/exploitation/api-agent/asynchronisme`. 2. Le subnet diff --git a/docs/developpement/lab.rst b/docs/developpement/lab.rst index 632e03a..1266dbc 100644 --- a/docs/developpement/lab.rst +++ b/docs/developpement/lab.rst @@ -298,9 +298,9 @@ Générée par ``test/e2e/run.sh --matrice`` à partir des en-têtes ; à régé - hv1 - #41, #57, #33, #62, #74 * - ``12-etats`` - - machine d'états — 409 pendant creating, suppression depuis error, dépendances VM → subnet → VPC, recréation sous le même nom + - machine d'états — 409 pendant creating, suppression depuis error, dépendances VM → subnet → VPC, suppression d'un subnet en attente de ses VM, arrêt d'une VM juste démarrée par renvoi de system_powerdown, recréation sous le même nom - hv1 - - #41 + - #41, #79 * - ``21-dhcp-two`` - DHCP par le serveur intégré (backend two) — bail, server-id, renouvellement, option 121, un serveur par subnet, démarrages simultanés - hv1 @@ -416,7 +416,7 @@ tests ont été corrigées sur le serveur et les tests concernés rejoués. Il r établie**. ``72-perte-switch`` n'exige donc plus que le plus prioritaire redevienne maître : il vérifie qu'il n'y a qu'un maître, note lequel, et mesure le plus long silence après le retour ; * une suppression de VM peut durer 300 s quand l'invité ignore l'arrêt ACPI (#79) : ``wait_state`` - attend jusqu'à 360 s. + attend jusqu'à 480 s, au-delà du ``times.timeout_vpc_stop`` par défaut (420 s). Hypothèses vérifiées en lab, à garder en tête en écrivant un test : diff --git a/docs/exploitation/api-agent/asynchronisme.rst b/docs/exploitation/api-agent/asynchronisme.rst index 7c4875b..926ae54 100644 --- a/docs/exploitation/api-agent/asynchronisme.rst +++ b/docs/exploitation/api-agent/asynchronisme.rst @@ -44,14 +44,18 @@ un état stable. Trois règles pour un appelant robuste : -* **Toujours borner l'attente.** Côté agent, ``dispatcher.timeout_seconds`` (300 s par défaut) - borne les opérations qui attendent une transition ; l'appelant doit avoir sa propre borne. +* **Toujours borner l'attente.** Côté agent, la section ``times`` de la configuration borne les + opérations qui attendent une transition ; l'appelant doit avoir sa propre borne. * **Traiter ``error`` comme terminal, pas comme un échec transitoire.** Un ``Execute`` en échec ne se rejoue pas tout seul. * **Savoir ce qui s'enchaîne.** Créer un subnet dont le VPC est encore en ``creating``, ou démarrer une VM sur un subnet en ``creating``, est accepté : l'``Execute`` attend que le parent - passe ``running``, dans la limite de ``dispatcher.timeout_seconds`` ; au-delà, la ressource passe - en ``error``. Le refus en 422 ne vaut que pour un parent absent, en ``error`` ou en ``deleting``. + passe ``running``, dans la limite de ``times.timeout_subnet_start`` ou ``times.timeout_vms_start`` ; + au-delà, la ressource passe en ``error``. Le refus en 422 ne vaut que pour un parent absent, en + ``error`` ou en ``deleting``. À la suppression, c'est l'inverse : une VM puis son subnet, ou un + subnet puis son VPC, peuvent être supprimés d'un coup ; le parent attend que ses enfants en + ``deleting`` soient supprimés (``times.timeout_subnet_stop``, ``times.timeout_vpc_stop``), et passe + en ``error`` si l'un d'eux échoue. Codes de retour --------------- @@ -78,8 +82,8 @@ Codes de retour * - ``409`` - conflit d'existence ou d'état : ressource déjà créée, ou suppression depuis un état qui ne l'autorise pas ; pour un VPC, subnets encore présents, ``l3vni`` déjà utilisée par un - autre VPC, ou ``l3vni`` demandée sans section ``bgp`` ; pour un subnet, VM non supprimées - qui l'utilisent encore + autre VPC, ou ``l3vni`` demandée sans section ``bgp`` ; pour un subnet, VM qui l'utilisent + encore, ni supprimées ni en ``deleting`` * - ``422`` - dépendance absente ou inutilisable : VPC parent d'un subnet, subnet d'une VM, absent, en ``error`` ou en ``deleting`` ; ``mode`` de subnet inconnu ; CIDR ``vxlan`` invalide ou plus diff --git a/docs/exploitation/configuration.rst b/docs/exploitation/configuration.rst index 30cb353..fcbdc61 100644 --- a/docs/exploitation/configuration.rst +++ b/docs/exploitation/configuration.rst @@ -72,21 +72,49 @@ Exécution des commandes count: 4 buffer_size: 100 - dispatcher: - timeout_seconds: 300 - poll_seconds: 2 + times: + timeout_vms_stop: 300 + next_vms_shutdown: 30 + timeout_subnet_stop: 360 + timeout_vpc_stop: 420 + timeout_subnet_start: 300 + timeout_vms_start: 300 + poll_interval: 2 ``worker.count`` est le nombre de goroutines qui exécutent les commandes ; ``buffer_size`` le nombre de commandes en attente au-delà duquel ``Dispatch`` bloque. -``dispatcher.timeout_seconds`` borne les opérations qui attendent une transition d'état, dont -l'extinction d'une VM. +La section ``times`` règle, en secondes, les attentes des commandes asynchrones : + +``timeout_vms_stop`` + arrêt propre d'une VM : au-delà, QEMU reçoit un ``quit`` QMP. +``next_vms_shutdown`` + intervalle entre deux ``system_powerdown`` pendant cet arrêt. Un invité qui n'écoutait pas + encore l'ACPI au premier appui (firmware, chargeur de démarrage) s'éteint au suivant. +``timeout_subnet_stop`` + suppression d'un subnet : attente de ses VM encore en ``deleting``. +``timeout_vpc_stop`` + suppression d'un VPC : attente de ses subnets encore en ``deleting``. +``timeout_subnet_start`` + création d'un subnet : attente de son VPC ``running``. +``timeout_vms_start`` + création d'une VM : attente des subnets de ses interfaces ``running``. +``poll_interval`` + pas de toutes ces attentes. + +Chaque valeur doit être strictement positive, et ``next_vms_shutdown`` inférieur à +``timeout_vms_stop`` ; sinon l'agent refuse de démarrer. Les attentes s'enchaînent — une VM, +puis son subnet, puis le VPC : garder ``timeout_vms_stop`` < ``timeout_subnet_stop`` < +``timeout_vpc_stop`` pour qu'une suppression en cascade envoyée d'un coup aboutisse. + +L'ancienne section ``dispatcher`` (``timeout_seconds``, ``poll_seconds``) n'est plus lue : restée +dans un fichier, elle est ignorée. .. warning:: - À l'expiration de ce délai, une VM qui ne s'est pas éteinte reçoit un ``quit`` QMP — un arrêt - **brutal**. Pour des charges dont l'extinction est lente (bases de données, construction - d'images), une valeur confortable évite un système de fichiers invité incohérent. + À l'expiration de ``timeout_vms_stop``, une VM qui ne s'est pas éteinte reçoit un ``quit`` + QMP — un arrêt **brutal**. Pour des charges dont l'extinction est lente (bases de données, + construction d'images), une valeur confortable évite un système de fichiers invité incohérent. Correspondance des interfaces ----------------------------- diff --git a/release_notes/0.3.0.md b/release_notes/0.3.0.md new file mode 100644 index 0000000..4cc841b --- /dev/null +++ b/release_notes/0.3.0.md @@ -0,0 +1,32 @@ +# Gabriel + +## Fonctionnalités + +**Délais dédiés : section `times` (#79)** + +- Nouvelle section `times` de la configuration, en secondes : `timeout_vms_stop` (300), + `next_vms_shutdown` (30), `timeout_subnet_stop` (360), `timeout_vpc_stop` (420), + `timeout_subnet_start` (300), `timeout_vms_start` (300), `poll_interval` (2). Elle remplace + `dispatcher.timeout_seconds` et `dispatcher.poll_seconds`, qui servaient à des attentes de + nature différente. Une valeur nulle ou négative, ou `next_vms_shutdown` au moins égal à + `timeout_vms_stop`, fait échouer le démarrage +- **Une VM et son subnet se suppriment d'un coup** : la suppression d'un subnet est acceptée + quand ses VM sont en `deleting`, et attend leur suppression jusqu'à `timeout_subnet_stop`. Le + 409 reste pour une VM ni supprimée ni en `deleting` + +## Correctifs + +- **`system_powerdown` est renvoyé toutes les `next_vms_shutdown` secondes (#79)** pendant + l'arrêt d'une VM, jusqu'à `timeout_vms_stop`. Un seul appui était envoyé : arrivé avant que + l'invité sache le traiter (firmware, chargeur de démarrage), il était perdu, et la suppression + durait les 300 s du délai avant un `quit` brutal (mesuré en lab) +- **La suppression d'un VPC échoue si l'un de ses subnets échoue (#79).** Elle attendait qu'aucun + subnet ne soit plus en `deleting`, puis supprimait le VPC même si un subnet était passé en + `error`. Il en va de même pour un subnet dont une VM attendue passe en `error` + +## Mise à jour depuis la 0.2.0 + +- **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 + qui en dépendent)