From 48f12958cf2befaf906a40d4b8045e88c2ffd5ee Mon Sep 17 00:00:00 2001 From: GnomeZworc Date: Fri, 23 Oct 2026 13:48:15 +0200 Subject: [PATCH] =?UTF-8?q?f-80:=20doc:=20commandes,=20chemins=20et=20code?= =?UTF-8?q?s=20align=C3=A9s=20sur=20le=20code,=20r=C3=A9pertoire=20uefi,?= =?UTF-8?q?=20route=20reflectors,=20sch=C3=A9mas=20r=C3=A9g=C3=A9n=C3=A9r?= =?UTF-8?q?=C3=A9s=20#80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: GnomeZworc --- README.md | 17 ++++---- conf/agent/config.exemple.yml | 2 +- docs/README.md | 4 +- docs/architecture/contraintes.rst | 5 --- docs/architecture/index.rst | 3 +- docs/architecture/vue-densemble.rst | 12 ++++++ docs/concepts/cycle-de-vie.rst | 5 ++- docs/concepts/metadata-cloud-init.rst | 12 +++--- docs/concepts/modes-reseau.rst | 13 ++++--- docs/concepts/vpc-subnet-vm.rst | 15 +++++-- docs/demarrage/installation.rst | 22 +++++++---- docs/demarrage/premier-vpc.rst | 29 ++++++++------ docs/deploiement/architecture-cluster.rst | 27 ++++++++----- docs/deploiement/index.rst | 2 +- docs/deploiement/premier-hyperviseur.rst | 17 ++++---- docs/deploiement/route-reflector.rst | 27 +++++++------ docs/deploiement/routeurs.rst | 23 +++++------ docs/developpement/lab.rst | 39 ++++++++++++------- docs/exploitation/api-agent/asynchronisme.rst | 23 +++++++---- docs/exploitation/configuration.rst | 3 +- docs/exploitation/diagnostic.rst | 15 ++++--- docs/exploitation/observabilite.rst | 14 ++++--- docs/exploitation/services.rst | 13 ++++--- docs/schemas/architecture-cluster-dark.svg | 28 +++++++------ docs/schemas/architecture-cluster.svg | 28 +++++++------ docs/schemas/architecture-ensemble-dark.svg | 14 ++++--- docs/schemas/architecture-ensemble.svg | 14 ++++--- docs/schemas/gen_cluster.py | 9 +++-- docs/schemas/gen_ensemble.py | 23 ++++------- release_notes/0.2.0.md | 3 ++ 30 files changed, 271 insertions(+), 190 deletions(-) diff --git a/README.md b/README.md index 538b2ae..17ed19a 100644 --- a/README.md +++ b/README.md @@ -22,20 +22,20 @@ Options utiles : | Option | Effet | |---|---| -| `-t ` | déployer une release donnée | -| `-b ` | déployer depuis une branche au lieu d'une release | +| `-t ` | déployer une release donnée ; sans `-t`, la dernière publiée, préversions comprises | +| `-b /` | branche d'où viennent l'auto-mise à jour du script et le bootstrap (`main/` par défaut, `/` final obligatoire) ; les binaires viennent toujours d'une release | | `-i` | préparer l'host (paquets, noyau, réseau) | | `-u ` | interface physique d'uplink, `eno1` par défaut | | `-B ` | bridge principal auquel l'uplink est rattaché | | `-d` | dry-run : affiche les commandes sans les exécuter | -| `-V` | désactiver la vérification des sommes de contrôle | +| `--noverify` | désactiver la vérification des sommes de contrôle | Un déploiement relève les instances `dnsmasq@`, `dhcp@` et `metadata@` actives **avant** l'arrêt des services, et les redémarre ensuite — c'est la seule façon de savoir lesquelles relancer. ## Configuration -Un seul fichier, `/etc/two/agent.yml`, partagé par les trois binaires. Voir +Un seul fichier, `/etc/two/agent.yml`, partagé par les quatre binaires. Voir [`conf/agent/config.exemple.yml`](conf/agent/config.exemple.yml) pour l'ensemble des options : chemins de la base et des sockets QEMU, pool de workers, correspondance des types d'interface vers les bridges physiques, watchdog, API d'administration, journalisation. @@ -49,7 +49,7 @@ curl -X POST http://127.0.0.1:8080/vpcs \ # Un subnet en VXLAN dans ce VPC curl -X POST http://127.0.0.1:8080/subnets \ - -d '{"name": "sn-000001", "vpc": "vp-admin", "mode": "vxlan", "vxlan_id": 1, + -d '{"name": "sn-000001", "vpc": "vp-admin", "mode": "vxlan", "vxlan_id": 65537, "iface_type": "vms", "cidr": "10.1.0.0/23"}' # Une VM, avec une clé SSH et un user-data cloud-init en base64 @@ -58,7 +58,7 @@ curl -X POST http://127.0.0.1:8080/vms \ "metadata": {"sshkey": "ssh-ed25519 AAAA…", "user_data": "'"$(base64 -w0 < user-data.yml)"'"}, "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"}]}' + "storage": [{"path": "/var/lib/two/volumes/i-web.qcow2", "dev": "vda"}]}' ``` Les créations sont **asynchrones** : l'API répond `202` et l'état de la ressource passe de @@ -75,9 +75,10 @@ La spécification complète est dans [`api/agent.yaml`](api/agent.yaml). |---|---| | `agent` | processus principal : API, dispatcher, exécution, watchdog | | `metadata` | serveur de metadata cloud-init, une instance par VM dans le netns du VPC | -| `db` | inspection de la base clé-valeur en ligne de commande | +| `dhcp` | serveur DHCP intégré, une instance par subnet dans le netns du VPC, avec `dhcp.backend: two` | +| `db` | inspection de la base clé-valeur en ligne de commande ; ni publié ni déployé, à compiler (`go build ./cmd/db`) | -L'agent prend `-config`, les deux autres `-conf`. +L'agent prend `-config`, les trois autres `-conf`. ## Versions diff --git a/conf/agent/config.exemple.yml b/conf/agent/config.exemple.yml index 19a09f9..077f1d9 100644 --- a/conf/agent/config.exemple.yml +++ b/conf/agent/config.exemple.yml @@ -76,7 +76,7 @@ qemu: ovmf_code_path: "/usr/share/OVMF/OVMF_CODE.fd" ovmf_vars_template: "/usr/share/OVMF/OVMF_VARS.fd" # Per-VM UEFI variable store (writable copy, created at start / deleted at stop) - uefi_vars_dir: "/run/two/vms/efi" + uefi_vars_dir: "/run/two/vms/uefi" # QEMU Unix socket directories serial_dir: "/run/two/vms/serial" monitor_dir: "/run/two/vms/monitor" diff --git a/docs/README.md b/docs/README.md index 0ef7780..dcdfa07 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,10 +11,10 @@ pip install -r requirements.txt sphinx-autobuild . "${TMPDIR}/build" ``` -Construction simple : +Construction simple, avec les mêmes options que la CI (avertissements bloquants) : ```bash -sphinx-build -b html . _build/html +sphinx-build -b html -W --keep-going . _build/html ``` La référence de l'API est générée depuis `../api/agent.yaml` : c'est la source unique du diff --git a/docs/architecture/contraintes.rst b/docs/architecture/contraintes.rst index 42e8de2..5686cee 100644 --- a/docs/architecture/contraintes.rst +++ b/docs/architecture/contraintes.rst @@ -4,11 +4,6 @@ Invariants et pièges Contraintes découvertes en production ou en corrigeant des bugs. Les enfreindre casse quelque chose qui fonctionne, souvent en silence. -.. note:: - - Cette page reprend la section « Invariants et pièges » de ``CLAUDE.md``, qui reste la - référence de développement et fait foi en cas d'écart. - Réseau ------ diff --git a/docs/architecture/index.rst b/docs/architecture/index.rst index 8a1308e..c7d3ef4 100644 --- a/docs/architecture/index.rst +++ b/docs/architecture/index.rst @@ -2,8 +2,7 @@ Architecture ============ L'organisation interne de l'agent : découpage en paquets, stockage, et contraintes à ne pas -enfreindre. Ces pages s'adressent à qui modifie le code ; ``CLAUDE.md``, à la racine du dépôt, -reste la référence de développement et fait foi en cas d'écart. +enfreindre. Ces pages s'adressent à qui modifie le code. .. toctree:: :maxdepth: 1 diff --git a/docs/architecture/vue-densemble.rst b/docs/architecture/vue-densemble.rst index 2d200f5..8bcb08b 100644 --- a/docs/architecture/vue-densemble.rst +++ b/docs/architecture/vue-densemble.rst @@ -58,16 +58,28 @@ Paquets - cycle de vie d'une VM : tap, iptables, metadata, qemu * - ``internal/dhcp`` - plan d'adressage ip → mac, et configurations dnsmasq du backend historique + * - ``internal/dhcpbackend`` + - interface commune aux deux backends DHCP (``dnsmasq`` et ``two``), choisie par + ``dhcp.backend`` + * - ``internal/dhcpd`` + - moteur du serveur DHCP intégré : réservations en mémoire, réponses, écoute + * - ``internal/api/dhcp``, ``internal/client/dhcp`` + - protocole de la socket de contrôle du serveur DHCP intégré (``set-host``, ``probe``, + ``get-state``…), côté serveur et côté agent * - ``internal/metadata`` - serveur de metadata cloud-init et ses templates * - ``internal/watchdog`` - vérification périodique en lecture seule + * - ``internal/watchdog/notify`` + - émission des écarts relevés par le watchdog (journal) * - ``internal/config/agent`` - chargement par viper — tags ``mapstructure``, jamais ``yaml`` * - ``internal/prometheus/agent`` - collector des métriques ``syonad_*`` * - ``pkg/db/kv`` - wrapper Badger ; toutes les valeurs sont des chaînes plates + * - ``pkg/db/statefile`` + - fichier d'état JSON typé, écrit de façon atomique, utilisé par le backend DHCP ``two`` * - ``pkg/worker`` - pool de goroutines sur canal * - ``pkg/systemd`` diff --git a/docs/concepts/cycle-de-vie.rst b/docs/concepts/cycle-de-vie.rst index 43e6172..bf41484 100644 --- a/docs/concepts/cycle-de-vie.rst +++ b/docs/concepts/cycle-de-vie.rst @@ -10,7 +10,6 @@ VPC, subnets et VM partagent le même jeu d'états. creating --> running creating --> error running --> deleting - running --> error deleting --> deleted deleting --> error error --> deleting @@ -27,7 +26,9 @@ VPC, subnets et VM partagent le même jeu d'états. * - ``running`` - la ressource existe sur le système * - ``error`` - - ``Execute`` a échoué ; état **terminal**, il n'y a pas de reprise automatique + - ``Execute`` a échoué, ou la migration du démarrage a trouvé la ressource en ``creating`` ou + ``deleting`` ; état **terminal**, il n'y a pas de reprise automatique. Une ressource + ``running`` ne passe jamais en ``error`` * - ``deleting`` - suppression en cours * - ``deleted`` diff --git a/docs/concepts/metadata-cloud-init.rst b/docs/concepts/metadata-cloud-init.rst index 8bfd934..ec38c08 100644 --- a/docs/concepts/metadata-cloud-init.rst +++ b/docs/concepts/metadata-cloud-init.rst @@ -20,14 +20,14 @@ deux processus ne doivent pas partager une même instance. Documents servis ---------------- -Chaque document suit la même règle : +Quatre documents sont servis : ``meta-data``, ``user-data``, ``network-config`` et +``vendor-data``. Seul ``user-data`` vient de l'appelant : -* fourni par l'appelant → servi **verbatim**, l'agent n'interprète rien ; -* absent → le template par défaut est rendu ; -* fourni **vide** → servi vide. +* ``user_data`` fourni → servi **verbatim**, après décodage base64 ; l'agent n'interprète rien ; +* ``user_data`` absent ou **vide** → ``user-data`` servi vide : les deux cas sont équivalents. -Les deux derniers cas sont distincts, et c'est délibéré : fournir une chaîne vide est une façon -explicite de neutraliser un document. +``meta-data``, ``network-config`` et ``vendor-data`` sont **toujours** rendus depuis les templates +de l'agent ; ``vendor-data`` crée le compte ``syonad`` à partir de ``password`` et ``sshkey``. Champs de ``metadata`` ---------------------- diff --git a/docs/concepts/modes-reseau.rst b/docs/concepts/modes-reseau.rst index 519696c..8a0503d 100644 --- a/docs/concepts/modes-reseau.rst +++ b/docs/concepts/modes-reseau.rst @@ -149,11 +149,12 @@ Routes annoncées aux VM ----------------------- Les routes sont poussées par DHCP, dans l'**option 121** (routes statiques sans classe, -RFC 3442). Trois entrées y figurent : +RFC 3442). Trois entrées au plus y figurent : #. la route ``/32`` vers ``169.254.169.254``, le serveur de metadata ; -#. la route vers le CIDR du VPC ; -#. la route par défaut ``0.0.0.0/0``. +#. la route vers le CIDR du VPC, **sauf en mode** ``bridge`` ; +#. la route par défaut ``0.0.0.0/0``, **sur l'interface** ``primary`` **seulement** : les autres + interfaces d'une VM n'en reçoivent pas. .. important:: @@ -163,8 +164,8 @@ RFC 3442). Trois entrées y figurent : Route par défaut : ``default_route`` et ``gateway`` ---------------------------------------------------------- -Une route par défaut est **toujours** annoncée. Le champ ``default_route`` ne choisit que son -next-hop : +Une route par défaut est **toujours** annoncée à l'interface ``primary`` d'une VM, et à elle +seule. Le champ ``default_route`` ne choisit que son next-hop : ``default_route: false`` (défaut) next-hop = ``interface_ip`` du subnet, la gateway calculée en ``vxlan``. @@ -178,7 +179,7 @@ subnet relèvent de l'appelant. Fourni avec ``default_route: false``, il est ign Dans tous les modes sauf ``bridge``, la route vers le CIDR du VPC garde ``interface_ip`` comme next-hop : sur un subnet à IP publique, le trafic interne ne doit pas sortir par la gateway -publique. +publique. En mode ``bridge``, cette route n'est pas annoncée du tout. Pourquoi la route ``/32`` vers le serveur de metadata est indispensable ---------------------------------------------------------------------------- diff --git a/docs/concepts/vpc-subnet-vm.rst b/docs/concepts/vpc-subnet-vm.rst index ca9ebcc..5156a38 100644 --- a/docs/concepts/vpc-subnet-vm.rst +++ b/docs/concepts/vpc-subnet-vm.rst @@ -18,6 +18,12 @@ VPC Un VPC est un **network namespace** portant un espace d'adressage (``cidr``). C'est l'unité d'isolation : deux VPC ne se voient pas, et peuvent réutiliser les mêmes plages d'adresses. +À la création, l'agent relie le netns au bridge ``br-public`` de l'host par un veth +``vp--e`` (côté host) ↔ ``vp--i`` (côté netns, rattaché à un ``br-public`` propre au +netns). Ce nom de bridge est **en dur** : l'host doit porter un bridge ``br-public``, celui que +crée ``deploy.sh -i`` avec la valeur par défaut de ``-P`` (:doc:`/demarrage/installation`) ; +sans lui, toute création de VPC échoue. + Un VPC ne peut être supprimé que si tous ses subnets le sont déjà — sinon 409. Routage entre hyperviseurs : ``l3vni`` @@ -112,6 +118,9 @@ depuis le subnet, leur source canonique. Le schéma complet des clés est dans Nommage ------- -L'API est machine-to-machine : elle **ne valide pas** les conventions de nommage, à l'exception -du motif documenté pour les VPC (``vp-…``). Les exemples de cette documentation suivent la -convention ``vp-`` / ``sn-`` / ``i-``, mais c'est à l'appelant de la faire respecter. +L'API est machine-to-machine : elle **ne valide aucun nommage**, pas même le motif ``vp-…`` +indiqué par la spécification pour les VPC. Une contrainte est pourtant réelle : le nom d'un VPC +ou d'un subnet doit **contenir un « - »**, car l'identifiant système (``vp--e``, ``br-``, +``gw-``…) est ce qui suit le premier tiret. Un nom sans tiret fait paniquer l'agent. Les +exemples de cette documentation suivent la convention ``vp-`` / ``sn-`` / ``i-``, mais c'est à +l'appelant de la faire respecter. diff --git a/docs/demarrage/installation.rst b/docs/demarrage/installation.rst index cb2e941..e4a5b2a 100644 --- a/docs/demarrage/installation.rst +++ b/docs/demarrage/installation.rst @@ -31,10 +31,12 @@ depuis la release, et les vérifie contre le manifeste ``SHA256SUMS``. - Défaut * - ``-t `` - déployer une release donnée - - dernière - * - ``-b `` - - branche utilisée pour l'auto-mise à jour du script - - ``main`` + - dernière publiée, **préversions comprises** + * - ``-b /`` + - branche d'où viennent l'auto-mise à jour du script et les scripts de ``-i`` ; les + binaires viennent toujours d'une release. Le ``/`` final est **obligatoire** : l'URL est + concaténée sans séparateur (``-b dev`` donne ``…/branch/devscripts/…``) + - ``main/`` * - ``-p `` - profil d'host ; seul ``kvm`` installe les units de l'agent - ``kvm`` @@ -48,7 +50,8 @@ depuis la release, et les vérifie contre le manifeste ``SHA256SUMS``. - bridge principal, auquel l'uplink est rattaché - ``br-000000`` * - ``-P `` - - bridge supplémentaire, créé vide et réservé + - bridge supplémentaire, créé vide et réservé ; garder ``br-public``, nom attendu par + l'agent (voir ci-dessous) - ``br-public`` * - ``-R `` - délai avant le redémarrage de secours pendant la migration réseau @@ -89,6 +92,10 @@ ne se provisionne pas. Contrepartie assumée : tout le trafic inter-VM traverse **Réseau** — création du bridge réservé, puis rattachement de l'uplink au bridge principal, l'adresse et la route par défaut étant déplacées de l'interface physique vers le bridge. +Le nom ``br-public`` est **en dur dans l'agent** : chaque VPC ``vp-`` y raccorde un veth +``vp--e`` côté host, dont l'autre extrémité ``vp--i`` rejoint un ``br-public`` créé dans +le netns du VPC. Avec un autre nom passé à ``-P``, toute création de VPC échoue. + .. danger:: La migration réseau **coupe le réseau de l'host si elle échoue à mi-parcours**, sans console @@ -124,14 +131,15 @@ Binaires installés - serveur de metadata cloud-init, une instance par VM dans le netns du VPC - ``-conf`` * - ``db`` - - inspection de la base clé-valeur en ligne de commande + - inspection de la base clé-valeur en ligne de commande ; **ni publié ni déployé** par + ``deploy.sh``, à compiler depuis les sources (:doc:`/exploitation/observabilite`) - ``-conf`` * - ``dhcp`` - serveur DHCP intégré, une instance par subnet dans le netns du VPC ; démarré uniquement avec ``dhcp.backend: two`` - ``-conf`` -Les quatre partagent le même fichier, ``/etc/two/agent.yml`` — voir +Les quatre lisent le même fichier, ``/etc/two/agent.yml`` — voir :doc:`/exploitation/configuration`. ``dhcp`` reçoit en plus son bridge et ses deux chemins de fichiers en paramètres, posés par son script d'enrobage. diff --git a/docs/demarrage/premier-vpc.rst b/docs/demarrage/premier-vpc.rst index 567b5bc..534dd55 100644 --- a/docs/demarrage/premier-vpc.rst +++ b/docs/demarrage/premier-vpc.rst @@ -14,16 +14,19 @@ Ce que l'on construit graph LR subgraph netns vp-admin - BR["br-sn000001
10.1.1.254"] + BR["br-000001
10.1.1.253"] + GW["gw-000001
gateway 10.1.1.254"] MD["metadata@i-web
169.254.169.254"] end VM["VM i-web
10.1.1.2"] --- BR - BR --- MD - BR --- VXLAN["VXLAN vni 1
br-000000"] + BR --- GW + GW --- MD + BR --- VXLAN["VXLAN vni 65537
br-000000"] -Le VPC est un network namespace ; le subnet y pose un bridge porteur de la gateway ; la VM s'y -raccroche par un tap, reçoit son adresse en DHCP et son cloud-init depuis le serveur de metadata -du netns. +Le VPC est un network namespace ; le subnet y pose un bridge ``br-000001`` — ``br-`` suivi de ce +qui suit le premier tiret du nom du subnet — porteur de l'adresse d'émission, et un macvlan +``gw-000001`` porteur de la gateway ; la VM se raccroche au bridge par un tap, reçoit son +adresse en DHCP et son cloud-init depuis le serveur de metadata du netns. 1. Le VPC --------- @@ -43,8 +46,10 @@ La réponse est un **202** : la création est acceptée, pas terminée. curl -s http://127.0.0.1:8080/vpcs/vp-admin -Attendez ``"state": "running"`` avant l'étape suivante — un subnet dont le VPC parent n'est pas -prêt est refusé en **422**. Le modèle d'attente est décrit dans :doc:`/exploitation/api-agent/asynchronisme`. +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`` +ou en ``deleting``. Le modèle d'attente est décrit dans :doc:`/exploitation/api-agent/asynchronisme`. 2. Le subnet ------------ @@ -56,7 +61,7 @@ prêt est refusé en **422**. Le modèle d'attente est décrit dans :doc:`/explo -d '{"name": "sn-000001", "vpc": "vp-admin", "mode": "vxlan", - "vxlan_id": 1, + "vxlan_id": 65537, "iface_type": "vms", "cidr": "10.1.0.0/23"}' @@ -140,16 +145,16 @@ cloud-init, lui, se déroule dans le guest ; on l'observe par la console série socat -,raw,echo=0 UNIX-CONNECT:/run/two/vms/serial/i-web.sock -Puis, depuis l'host : +Puis, depuis l'host, en passant par le netns du VPC : .. code-block:: bash - ssh syonad@10.1.1.2 + ip netns exec vp-admin ssh syonad@10.1.1.2 .. note:: En mode ``vxlan``, la VM vit dans le netns du VPC : elle n'est pas joignable depuis l'host - sans route explicite. En mode ``bridge``, elle l'est directement. + sans route explicite, d'où le ``ip netns exec``. En mode ``bridge``, elle l'est directement. 5. Supprimer ------------ diff --git a/docs/deploiement/architecture-cluster.rst b/docs/deploiement/architecture-cluster.rst index b0957b8..d0898dd 100644 --- a/docs/deploiement/architecture-cluster.rst +++ b/docs/deploiement/architecture-cluster.rst @@ -24,9 +24,9 @@ Vue d'ensemble (BGP). Tirets verts : orchestration. Trait orange : trafic Internet. Cadre en pointillés : élément à venir, avec son ticket. -Plusieurs clusters, chacun avec son underlay, ses deux routeurs et un route reflector, sont reliés -en eBGP entre eux et aux **routeurs de bordure**. Ce qui n'existe pas encore est décrit sur son -ticket : +Plusieurs clusters, chacun avec son underlay et ses deux routeurs, sont reliés en eBGP entre eux +et aux **routeurs de bordure** ; les route reflectors sont décrits plus bas. Ce qui n'existe pas +encore est décrit sur son ticket : * **Internet** (`#31 `_, `#42 `_). Les bordures partagent avec les hyperviseurs @@ -41,12 +41,19 @@ ticket : * **Orchestration** (`#72 `_). Le broker et l'orchestrateur sont des VM du VNI 66000, partagé entre clusters. Les agents s'y connectent - **en sortie**, par leur passerelle ; les routeurs de chaque cluster les NAT vers le VNI 66000. + **en sortie**, par leur passerelle ; les routeurs de chaque cluster les traduisent (NAT) vers le + VNI 66000. L'orchestrateur a aussi une patte dans le VNI 66001 : son API est joignable depuis Internet. -* **Route reflectors.** Un par cluster, pour qu'un incident sur un cluster ne coupe pas les deux - sessions EVPN. Chaque lien entre routeurs et route reflector est en ``169.254.0.0/28``, propre - à son cluster. +* **Route reflectors.** Au moins un ; deux sont prévus dans l'architecture et dans les exemples + (plages d'adresses de :doc:`route-reflector`), placés ici dans deux clusters différents pour + qu'un incident sur un cluster ne coupe pas les deux sessions EVPN. Chaque lien entre routeurs + et route reflector est en ``169.254.0.0/28``, propre à son cluster. Le ``bgp listen range`` de + chaque route reflector doit alors couvrir l'underlay de **tous** les clusters qu'il sert — + l'exemple ``rr1.conf`` n'accepte que ``192.168.14.0/24``. + +* **ASN.** Les routeurs de deux clusters étant voisins eBGP, chaque cluster a son propre ASN de + routeurs : l'AS 65100 des exemples est la valeur d'**un** cluster. Le lab (:doc:`/developpement/lab`) simplifie : un seul cluster, qui porte les deux route reflectors. @@ -79,7 +86,7 @@ Plan de données Plan de contrôle ce qui dit à chaque hyperviseur où se trouvent les adresses MAC des autres. C'est le rôle de - FRR et du route reflector. + FRR et des route reflectors. Ce que l'agent suppose déjà en place ------------------------------------ @@ -111,8 +118,8 @@ apprentissage des adresses MAC depuis le trafic, ni voisin statique configuré. isolé le trafic reste sur le bridge local et cette absence ne se voit pas ; elle apparaît dès le deuxième nœud. -C'est exactement le rôle que remplissent FRR sur chaque hyperviseur et le route reflector qui -les fait converger. +C'est exactement le rôle que remplissent FRR sur chaque hyperviseur et les route reflectors qui +les font converger. MTU --- diff --git a/docs/deploiement/index.rst b/docs/deploiement/index.rst index 9586f3a..7b958d4 100644 --- a/docs/deploiement/index.rst +++ b/docs/deploiement/index.rst @@ -7,7 +7,7 @@ même nœud. Cette section couvre la mise en place d'un **cluster** complet, dan Cet ordre n'est pas indifférent : chaque étape a besoin de la précédente. L'image doit exister avant qu'on puisse démarrer quoi que ce soit ; le réseau doit être en place avant le premier -hyperviseur ; le route reflector est lui-même une VM, il lui faut donc un hyperviseur qui +hyperviseur ; chaque route reflector est lui-même une VM, il lui faut donc un hyperviseur qui fonctionne. Étapes diff --git a/docs/deploiement/premier-hyperviseur.rst b/docs/deploiement/premier-hyperviseur.rst index 4e1c451..6f2b757 100644 --- a/docs/deploiement/premier-hyperviseur.rst +++ b/docs/deploiement/premier-hyperviseur.rst @@ -62,13 +62,13 @@ L'agent en déduit la configuration ci-dessous ; le ``router-id`` est l'adresse Avec une section ``bgp``, l'agent **refuse de démarrer** si ``vtysh`` ne répond pas, et ``agent.service`` ne le relance pas. L'ordre au démarrage est donc : migration réseau vers ``br-000000``, **puis** FRR, **puis** l'agent. FRR démarré avant la migration peut perdre la - route par défaut quand elle change d'interface, et ne plus joindre le route reflector. + route par défaut quand elle change d'interface, et ne plus joindre les route reflectors. Ce qu'elle établit : * **Une session par route reflector**, en iBGP dans l'AS 64600, vers sa loopback (``10.255.255.1``, ``10.255.255.2``), jointe par la passerelle par défaut — le routeur de - cluster l'a apprise du route reflector (:doc:`routeurs`). Aucune adresse d'un autre hyperviseur n'est écrite : ajouter + cluster l'a apprise de ce route reflector (:doc:`routeurs`). Aucune adresse d'un autre hyperviseur n'est écrite : ajouter un nœud ne touche pas la configuration des autres. * **EVPN seulement** : l'IPv4 unicast n'est pas activé (``no bgp default ipv4-unicast``). ``advertise-all-vni`` annonce les VNI de toutes les interfaces VXLAN que FRR voit, et donc @@ -81,9 +81,9 @@ Articulation avec l'agent Rien à configurer à la création d'un subnet : la VXLAN apparaît, FRR la voit et l'annonce, sans action ni redémarrage. Il faut en revanche que la VXLAN porte une **adresse VTEP locale** : sans elle, FRR voit la VNI mais n'annonce rien, et deux hyperviseurs gérés par two ne se joignent pas. -L'agent la pose à partir de la release ``0.2.0rc003`` -(`#51 `_) : l'adresse IPv4 primaire du ``local_iface`` -du subnet. +L'agent la pose depuis la version 0.2.0 (préversions comprises à partir de ``0.2.0rc003``, +`#51 `_, fermé) : l'adresse IPv4 primaire du +``local_iface`` du subnet. .. note:: @@ -93,11 +93,10 @@ du subnet. et configuration doivent être posés à chaque démarrage, par le bootstrap ou un mécanisme équivalent (`#52 `_) ; * le démarrage à froid, selon que FRR démarre avant ou après l'agent ; - * les subnets ``vxlan`` créés avant ``0.2.0rc003``, dont la VXLAN n'a pas d'adresse VTEP - locale : les recréer ou poser l'adresse à chaud, à trancher dans - `#51 `_ ; + * les subnets ``vxlan`` créés par une version antérieure, dont la VXLAN n'a pas d'adresse VTEP + locale : aucune migration ne la pose, il faut les recréer ; * le cas particulier du **premier** hyperviseur, dont la session ne peut pas s'établir tant - que le route reflector n'existe pas. + qu'aucun route reflector n'existe. Vérifier le plan de données --------------------------- diff --git a/docs/deploiement/route-reflector.rst b/docs/deploiement/route-reflector.rst index f8b5bc7..7cbd8f8 100644 --- a/docs/deploiement/route-reflector.rst +++ b/docs/deploiement/route-reflector.rst @@ -3,9 +3,11 @@ VM route reflector Le route reflector est le point de rendez-vous du plan de contrôle : plutôt que de maintenir une session entre chaque paire d'hyperviseurs, chaque hyperviseur ouvre une session vers le route -reflector, qui redistribue. Le cluster en compte **deux**, configurés à l'identique hormis leurs -adresses : chaque hyperviseur ouvre une session vers chacun, et la perte de l'un ne doit pas -interrompre le plan de contrôle (`#54 `_). +reflector, qui redistribue. Un cluster en compte **au moins un** ; l'architecture et les exemples +de cette page en prévoient **deux** (rr1 et rr2, d'où les plages d'adresses ci-dessous), +configurés à l'identique hormis leurs adresses : chaque hyperviseur ouvre une session vers chacun, +et la perte de l'un n'interrompt pas le plan de contrôle +(`#54 `_, fermé). Il tourne lui-même en machine virtuelle, ce qui crée une dépendance circulaire à traiter explicitement : la VM qui porte le plan de contrôle du cluster est hébergée par le cluster. @@ -84,13 +86,14 @@ Ce qu'elle établit : .. warning:: - **Les tunnels ne survivent pas à la perte du route reflector.** Avec un seul route reflector - et sans ``graceful-restart``, à l'arrêt de FRR sur le route reflector, la session EVPN des - hyperviseurs tombe aussitôt, FRR retire les routes apprises et, avec elles, le VTEP distant et l'entrée d'inondation du VXLAN — **plus - aucun paquet ne passe** entre hyperviseurs, à 30 s comme à 90 s. Au redémarrage de FRR sur le - route reflector, VTEP distant et trafic reviennent **31 s** plus tard. Le trafic entre VM d'un - même hyperviseur n'est pas concerné. La redondance (deux route reflectors) ou - ``graceful-restart`` sont les deux leviers ; ni l'un ni l'autre n'est encore qualifié. + **Les tunnels ne survivent pas à la perte de tous les route reflectors.** Sans + ``graceful-restart``, quand plus aucun route reflector ne répond, les sessions EVPN des + hyperviseurs tombent, FRR retire les routes apprises et, avec elles, le VTEP distant et + l'entrée d'inondation du VXLAN : **plus aucun paquet ne passe** entre hyperviseurs, jusqu'au + retour d'un route reflector et à la reconvergence des sessions. Le trafic entre VM d'un même + hyperviseur n'est pas concerné. Avec deux route reflectors, la perte de l'un est sans effet sur + le trafic, à condition qu'ils ne tombent jamais ensemble : **jamais deux route reflectors sur le + même hyperviseur**. Les mesures du lab sont dans :doc:`/developpement/lab`. .. note:: @@ -101,8 +104,8 @@ Ce qu'elle établit : autres ou d'un cas particulier — l'image, elle, est l'image golden de :doc:`image-qcow2` ; * le placement des deux VM : jamais sur le même hyperviseur, et de préférence pas sur un hyperviseur dont la perte isolerait l'autre ; - * la procédure de reconstruction — l'état du cluster pendant l'absence du route reflector est - décrit ci-dessus : plus de trafic entre hyperviseurs ; + * la procédure de reconstruction — l'état du cluster pendant l'absence de tous les route + reflectors est décrit ci-dessus : plus de trafic entre hyperviseurs ; * la procédure d'amorçage : ce qui fonctionne, et dans quel ordre, quand on démarre un cluster entier depuis zéro — le premier hyperviseur n'a pas de session FRR établie tant que cette VM n'existe pas, cf. :doc:`premier-hyperviseur`. diff --git a/docs/deploiement/routeurs.rst b/docs/deploiement/routeurs.rst index 78337ea..4f3b957 100644 --- a/docs/deploiement/routeurs.rst +++ b/docs/deploiement/routeurs.rst @@ -18,9 +18,10 @@ Routeurs de bordure Routeur de cluster ------------------ -Le routeur de cluster est la passerelle des hyperviseurs et le voisin eBGP des deux route -reflectors, dont il apprend les loopbacks : c'est par lui que chaque hyperviseur joint -``10.255.255.1`` et ``10.255.255.2`` pour ouvrir ses sessions EVPN (:doc:`route-reflector`). +Le routeur de cluster est la passerelle des hyperviseurs et le voisin eBGP des route reflectors +— au moins un ; deux sont prévus dans l'architecture et dans les exemples —, dont il apprend les +loopbacks : c'est par lui que chaque hyperviseur joint ``10.255.255.1`` et ``10.255.255.2`` pour +ouvrir ses sessions EVPN (:doc:`route-reflector`). Adressage ~~~~~~~~~ @@ -33,8 +34,9 @@ Adressage - Interface - Rôle * - ``192.168.14.1/24`` - - interface du segment des hyperviseurs - - passerelle par défaut des hyperviseurs et du route reflector + - interface du segment des hyperviseurs, **adresse virtuelle VRRP** + - passerelle par défaut des hyperviseurs et des route reflectors, portée par le routeur + maître ; chaque routeur a en plus sa propre adresse sur le segment * - ``169.254.0.1/28`` - même interface, **adresse secondaire** - lien avec les route reflectors (``169.254.0.3`` et ``.4``) ; ``router-id`` ; le second @@ -60,9 +62,9 @@ Ce qu'elle établit : * **Aucune session avec les hyperviseurs** : le routeur leur sert de passerelle, pas de voisin BGP. Celle du second routeur (``test/e2e/topologies/frr/sw2.conf``) ne diffère que par ``hostname`` et -``router-id`` (``169.254.0.2``), que les route reflectors déclarent aussi. La redondance des -routeurs — et le mécanisme qui fait basculer la passerelle ``192.168.14.1`` — est l'objet de -`#54 `_. +``router-id`` (``169.254.0.2``), que les route reflectors déclarent aussi. Les deux routeurs se +partagent la passerelle ``192.168.14.1`` en **VRRP v3** : le maître la porte, l'autre attend, sans +préemption (`#54 `_, fermé). .. note:: @@ -73,9 +75,8 @@ routeurs — et le mécanisme qui fait basculer la passerelle ``192.168.14.1`` **À rédiger.** Reste à documenter, faute d'éléments de terrain : - * pour le routeur de cluster : le matériel employé et sa version de référence ; la redondance - — deux routeurs, mécanisme de bascule, comportement attendu pendant une bascule - (`#54 `_) ; + * pour le routeur de cluster : le matériel employé et sa version de référence ; la traduction + de la redondance VRRP v3 dans sa configuration ; * pour les routeurs de datacentre et de bordure : tout — équipement, configuration de référence, ce qui est annoncé et filtré à chaque niveau, redondance ; * l'ordre de mise en service, et ce qui doit être opérationnel avant de préparer le premier diff --git a/docs/developpement/lab.rst b/docs/developpement/lab.rst index 9544df6..9e66943 100644 --- a/docs/developpement/lab.rst +++ b/docs/developpement/lab.rst @@ -4,7 +4,7 @@ Lab de test multi-nœud Ce qui fait l'intérêt de two ne se voit qu'à partir de **deux hyperviseurs** : sur un nœud isolé, le trafic reste sur le bridge local et l'absence de plan de contrôle passe inaperçue (voir :doc:`/deploiement/architecture-cluster`). Le lab reproduit la topologie du cluster — -hyperviseurs, route reflector, switch L3 — sous forme de VM, sur un serveur physique loué à +hyperviseurs, route reflectors, switchs L3 — sous forme de VM, sur un serveur physique loué à l'heure. Le pourquoi des choix (serveur physique plutôt que VM cloud, câbles QEMU, MTU 9000, versions) est @@ -17,7 +17,8 @@ comment s'en servir. `labctl `_, un dépôt à part, dont two épingle une release. Ce dépôt garde ce qui est propre à two — ses topologies, l'installation de two sur les hyperviseurs, les scénarios et leurs résultats. La redondance du plan de contrôle — deux route - reflectors, deux switchs — est l'objet de `#54 `_. + reflectors, deux switchs en VRRP v3 — est livrée par `#54 `_ + (fermé), et qualifiée par les tests 71 et 72. L'outil ------- @@ -69,7 +70,7 @@ et ``evpn-3hv.yml`` (trois, celle de la suite). Le format est celui de ``labctl` .. literalinclude:: ../../test/e2e/topologies/evpn-2hv.yml :language: yaml -Les ASN, la loopback du route reflector, le lien ``169.254.0.0/28`` et le subnet des hyperviseurs +Les ASN, les loopbacks des route reflectors, le lien ``169.254.0.0/28`` et le subnet des hyperviseurs de l'exemple sont **ceux de la production** (décision du 2026-10-04, #50) : les fichiers de ``test/e2e/topologies/`` restent ainsi au plus près de ce qui tourne réellement. Toutes les adresses y sont **fixées** par ``addresses`` — les switchs en ``.2`` et ``.3``, les route reflectors en ``.4`` et ``.5``, @@ -77,8 +78,9 @@ les hyperviseurs à partir de ``.11`` — pour que le modèle se lise sans le pl de l'ordre de déclaration : le ``frr.conf`` d'un hyperviseur, écrit à la main, porte son adresse en ``router-id``. Les deux switchs ``sw1`` et ``sw2`` sont les routeurs du segment (rôle ``router`` de labctl) : la passerelle, la première adresse du segment, est portée en VRRP v3 par celui qui est -maître, sans préemption — voir la section du guide de labctl sur les routeurs. Leurs -``frr.conf`` ne diffèrent que par ``hostname`` et ``router-id`` ; labctl y ajoute la strophe VRRP. +maître, sans préemption (``no vrrp 1 preempt``) — voir la section du guide de labctl sur les +routeurs. Leurs ``frr.conf`` ne diffèrent que par ``hostname`` et ``router-id`` ; labctl y ajoute +la strophe VRRP. Rôles ~~~~~ @@ -86,8 +88,8 @@ Rôles Les configurations FRR du lab vivent dans ``test/e2e/topologies/frr/``, une par nœud, **écrites à la main** : ce sont les mêmes fichiers que la documentation de déploiement inclut, pour que le lab qualifie exactement ce qu'elle prescrit. Celles des hyperviseurs se réduisent à ``hostname`` et ``log`` : -la configuration BGP est posée par l'agent (section ``bgp`` de ``agent.yml``). Celle du route -reflector : +la configuration BGP est posée par l'agent (section ``bgp`` de ``agent.yml``). Celle du premier +route reflector (celle de ``rr2`` ne diffère que par son nom et sa loopback) : .. literalinclude:: ../../test/e2e/topologies/frr/rr1.conf :language: text @@ -239,7 +241,7 @@ Les tests se lancent **depuis le Mac**, sur un lab démarré (``up``, ``push``, test/e2e/run.sh all # toute la suite, dans l'ordre test/e2e/run.sh 40 # une couche - test/e2e/run.sh 41 43 # des tests, par numéro ou par nom + test/e2e/run.sh 41 dhcp-two # des tests, par numéro à deux chiffres ou par nom exact test/e2e/run.sh --from 30 # à partir d'un numéro test/e2e/run.sh --continue all # sans s'arrêter sur une couche en échec test/e2e/run.sh --connus all # les échecs connus comptent comme des échecs @@ -408,7 +410,10 @@ tests ont été corrigées sur le serveur et les tests concernés rejoués. Il r (#73, #62), noms des disques SCSI (#74), mode ``bridge`` sur plusieurs hôtes (#75), filtrage au port (#76), socket DHCP (#77), fausse alerte du watchdog (#78) ; * #69 vérifié : au retour de ``sw1`` (priorité 200), il redevient maître, seconde bascule en - 1,2 s, sessions EVPN jamais coupées ; + 1,2 s, sessions EVPN jamais coupées. La préemption est pourtant **désactivée** dans la + configuration (``no vrrp 1 preempt``, « Preempt Mode No » relevé le 2026-10-23) : la cause de ce + retour, après coupure puis rétablissement de l'interface underlay du maître, **n'est pas + établie** ; * une suppression de VM peut durer 300 s quand l'invité ignore l'arrêt ACPI (#79) : ``wait_state`` attend jusqu'à 360 s. @@ -436,18 +441,22 @@ Un test est un fichier ``test/e2e/suite/NN-nom.sh``, exécuté par ``run.sh`` su commence par un en-tête, puis envoie des blocs aux nœuds par ``on [VAR=valeur…] <<'NODE'``. Chaque bloc est précédé des bibliothèques de ``test/e2e/lib/`` : -* ``core.sh`` : ``check``, ``known``, ``info``, appels à l'API, attente des états ; +* ``core.sh`` : ``check``, ``known``, ``known_flaky``, ``info``, appels à l'API, attente des états ; * ``vm.sh`` : image Debian compatible two, clé SSH, ``vm_launch`` (plusieurs NIC et disques, UEFI, ``user_data``, mot de passe), SSH, bail, métadonnées. La MAC de chaque NIC est fournie à l'API : ``52:54:00`` suivi des trois derniers octets de l'IP (``mac_for_ip``), unique dans la suite puisque chaque test a sa plage ; ``--nic sn=ip=mac`` en impose une autre ; * ``net.sh`` : VPC, subnets, MAC anycast, trames brutes, règles ebtables, VRRP ; * ``evpn.sh`` : VRF, BGP, L3VNI, watchdog ; -* ``fixture.sh`` : nettoyage et ``assert_clean``, appelés par le runner. +* ``fixture.sh`` : nettoyage et ``assert_clean``, appelés par le runner. Le nettoyage couvre les + ressources ``t`` de l'API, les netns ``t-*`` et les fichiers ``t-*`` / ``t.*`` de + ``/tmp`` et ``/var/tmp/e2e`` (sauf l'état ``t.avant``) ; il ne joue que pour un test dont + l'en-tête « # hôtes: » est rempli. Un test sans aucune vérification propre, hors fixtures, est + en échec. .. code-block:: bash - # fonctionnalité: trafic entre deux VM d'un même subnet sur un hôte + # fonctionnalité: trafic entre deux VM d'un même subnet sur un hôte, isolation entre VPC # hôtes: hv1 # tickets: #NN @@ -459,7 +468,11 @@ Chaque bloc est précédé des bibliothèques de ``test/e2e/lib/`` : check "VM t99-b" vm_launch t99-b --nic sn-t99=10.99.1.11 --sshkey "${KEY}" check "t99-a joignable" vm_wait vp-t99 10.99.1.10 check "t99-a joint t99-b" vm_ssh vp-t99 10.99.1.10 'ping -c 2 -W 2 10.99.1.11' - check "t99-a ne joint pas 10.98.1.10" vm_fails vp-t99 10.99.1.10 'ping -c 2 -W 2 10.98.1.10' + check "VPC vp-t99b" vpc_create vp-t99b 10.99.0.0/16 + check "subnet sn-t99b" subnet_create sn-t99b vp-t99b 9902 10.99.2.0/24 + check "VM t99-c" vm_launch t99-c --nic sn-t99b=10.99.2.10 --sshkey "${KEY}" + check "t99-c joignable dans son VPC" vm_wait vp-t99b 10.99.2.10 + check "t99-a ne joint pas t99-c (autre VPC)" vm_fails vp-t99 10.99.1.10 'ping -c 2 -W 2 10.99.2.10' NODE Les règles : diff --git a/docs/exploitation/api-agent/asynchronisme.rst b/docs/exploitation/api-agent/asynchronisme.rst index afcee1d..7c4875b 100644 --- a/docs/exploitation/api-agent/asynchronisme.rst +++ b/docs/exploitation/api-agent/asynchronisme.rst @@ -48,9 +48,10 @@ Trois règles pour un appelant robuste : 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. -* **Ne pas enchaîner sans vérifier.** Créer un subnet dont le VPC est encore en ``creating`` - échoue en 422 ; démarrer une VM sur un subnet en ``creating`` ou ``running`` est en revanche - accepté. +* **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``. Codes de retour --------------- @@ -66,15 +67,23 @@ Codes de retour * - ``200`` - lecture réussie (``GET``) * - ``400`` - - champ obligatoire manquant, corps invalide, ``iface_type`` inconnu, base64 invalide + - champ obligatoire manquant, corps invalide, base64 invalide ; CIDR de VPC invalide, + ``l3vni`` hors plage ; ``interface_ip`` absent (``bridge``, ``public_ip``) ou fourni + (``vxlan``) ; interface de VM sans ``mac``, nombre d'interfaces ``primary`` différent de 1 * - ``404`` - ressource inexistante + * - ``405`` + - méthode non prise en charge ; corps ``{"error": "method not allowed"}``, mais servi en + ``text/plain`` par ``/vpcs`` et ``/subnets`` (et leurs ``/{name}``), en JSON par ``/vms`` * - ``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 ; pour un subnet, VM non - supprimées qui l'utilisent encore + 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 * - ``422`` - - dépendance absente ou pas prête : VPC parent d'un subnet, subnet d'une VM + - 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 + petit que ``/29`` ; IP de VM hors du CIDR du subnet ou réservée * - ``500`` - erreur interne diff --git a/docs/exploitation/configuration.rst b/docs/exploitation/configuration.rst index 4d67e98..c05aad7 100644 --- a/docs/exploitation/configuration.rst +++ b/docs/exploitation/configuration.rst @@ -173,7 +173,7 @@ Metadata et QEMU qemu: ovmf_code_path: "/usr/share/OVMF/OVMF_CODE.fd" ovmf_vars_template: "/usr/share/OVMF/OVMF_VARS.fd" - uefi_vars_dir: "/run/two/vms/efi" + uefi_vars_dir: "/run/two/vms/uefi" serial_dir: "/run/two/vms/serial" monitor_dir: "/run/two/vms/monitor" qmp_dir: "/run/two/vms/qmp" @@ -257,6 +257,7 @@ Watchdog interval_seconds: 60 Vérification périodique **en lecture seule** — voir :doc:`/exploitation/observabilite`. +**Désactivée par défaut** (``enabled: false``) : sans cette section, aucun contrôle ne tourne. Journalisation -------------- diff --git a/docs/exploitation/diagnostic.rst b/docs/exploitation/diagnostic.rst index 8ed51fd..a813a62 100644 --- a/docs/exploitation/diagnostic.rst +++ b/docs/exploitation/diagnostic.rst @@ -49,7 +49,7 @@ Le DHCP est servi par une instance dédiée au subnet. Quelle unit selon ``dhcp. # Ce qu'il enverrait à une MAC donnée, sans effet de bord echo '{"verb":"probe","mac":"00:22:33:00:00:0A"}' \ - | socat - UNIX-CONNECT:/run/two/dhcp/_.sock | jq .lease + | socat - UNIX-CONNECT:/run/two/dhcp/_.sock | jq '{served, lease}' ``probe`` est le point de départ le plus rapide : il montre l'adresse, le masque, le routeur, les DNS et les routes classless tels qu'ils partiraient. Une réponse ``"served": false`` signifie que @@ -111,12 +111,14 @@ user-data. Vérification dans le guest : cloud-init query instance-id ls /var/lib/cloud/instances/ -**2. Le serveur de metadata est injoignable.** Depuis le guest : +**2. Le serveur de metadata est injoignable.** Depuis le guest — le serveur ne sert que +``/meta-data``, ``/user-data``, ``/network-config`` et ``/vendor-data``, tout autre chemin +renvoie 404 : .. code-block:: bash ip route - curl -s http://169.254.169.254/latest/meta-data/ + curl -s http://169.254.169.254/meta-data La route ``169.254.169.254/32`` doit être présente, avec l'``interface_ip`` du subnet comme next-hop. Si elle est absente ou pointe ailleurs, la DNAT posée en ``PREROUTING`` dans le netns @@ -133,8 +135,9 @@ Depuis l'host, l'instance correspondante : Le user-data est servi vide --------------------------- -Un document fourni explicitement vide est servi vide — ce n'est pas la même chose qu'un document -absent, qui retombe sur le template. Vérifier le contenu réellement écrit : +C'est le comportement attendu quand ``user_data`` est absent ou vide à la création : les deux cas +sont équivalents, et aucun template ne prend le relais pour ``user-data``. Vérifier le contenu +réellement écrit : .. code-block:: bash @@ -150,7 +153,7 @@ La VM ne démarre pas (UEFI) .. code-block:: bash ls -l /usr/share/OVMF/OVMF_CODE.fd /usr/share/OVMF/OVMF_VARS.fd - ls -l /run/two/vms/efi/ + ls -l /run/two/vms/uefi/ Sur Debian et Ubuntu, le paquet est ``ovmf``. diff --git a/docs/exploitation/observabilite.rst b/docs/exploitation/observabilite.rst index 6602dfa..46d1a37 100644 --- a/docs/exploitation/observabilite.rst +++ b/docs/exploitation/observabilite.rst @@ -27,7 +27,8 @@ Watchdog -------- Une goroutine périodique vérifie que les ressources marquées ``running`` en base existent -toujours sur le système, et **notifie les écarts sans jamais réparer**. +toujours sur le système, et **notifie les écarts sans jamais réparer**. Il est **désactivé par +défaut** (``enabled: false``) ; l'activer explicitement : .. code-block:: yaml @@ -72,17 +73,20 @@ Journaux journalctl -u agent -f journalctl -u 'metadata@i-web' -n 50 - tail -f /var/log/dnsmasq-vp-admin_br-sn000001.log # backend dnsmasq - journalctl -fu 'dhcp@vp-admin_br-sn000001' # backend two + tail -f /var/log/dnsmasq-vp-admin_br-000001.log # backend dnsmasq + journalctl -fu 'dhcp@vp-admin_br-000001' # backend two Inspection de la base --------------------- -En ligne de commande, sur l'host : +En ligne de commande, sur l'host. Le binaire ``db`` n'est **ni publié dans les releases ni +déployé** par ``deploy.sh`` : il se compile depuis les sources, puis se copie sur l'host. Sans +sous-commande, il n'affiche que son usage ; ``print`` liste toute la base : .. code-block:: bash - /opt/two/bin/db -conf /etc/two/agent.yml + CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o db ./cmd/db + ./db -conf /etc/two/agent.yml print .. warning:: diff --git a/docs/exploitation/services.rst b/docs/exploitation/services.rst index 9ddc968..d6ff8f7 100644 --- a/docs/exploitation/services.rst +++ b/docs/exploitation/services.rst @@ -1,7 +1,8 @@ Services systemd ================ -Quatre units, installées sous ``/opt/two/bin`` par ``deploy.sh``. Les deux units DHCP +Quatre units, installées dans ``/etc/systemd/system`` par ``deploy.sh`` ; les binaires et scripts +qu'elles lancent sont sous ``/opt/two/bin``. Les deux units DHCP s'excluent : celle qui tourne dépend de ``dhcp.backend`` (voir :doc:`configuration`). .. list-table:: @@ -30,8 +31,8 @@ n'y a pas à les démarrer à la main en fonctionnement normal. .. code-block:: bash systemctl status agent - systemctl status 'dnsmasq@vp-admin_br-sn000001' # backend dnsmasq - systemctl status 'dhcp@vp-admin_br-sn000001' # backend two + systemctl status 'dnsmasq@vp-admin_br-000001' # backend dnsmasq + systemctl status 'dhcp@vp-admin_br-000001' # backend two systemctl status 'metadata@i-web' dnsmasq @@ -65,9 +66,9 @@ ignore le netns dans lequel il tourne : .. code-block:: bash /opt/two/bin/dhcp -conf /etc/two/agent.yml \ - -interface br-sn000001 \ - -state /run/two/dhcp/vp-admin_br-sn000001.state \ - -socket /run/two/dhcp/vp-admin_br-sn000001.sock + -interface br-000001 \ + -state /run/two/dhcp/vp-admin_br-000001.state \ + -socket /run/two/dhcp/vp-admin_br-000001.sock .. list-table:: :widths: 40 60 diff --git a/docs/schemas/architecture-cluster-dark.svg b/docs/schemas/architecture-cluster-dark.svg index b5a92d4..9ad0845 100644 --- a/docs/schemas/architecture-cluster-dark.svg +++ b/docs/schemas/architecture-cluster-dark.svg @@ -1,4 +1,4 @@ - + ").replace( " ", ' \n ') diff --git a/docs/schemas/gen_ensemble.py b/docs/schemas/gen_ensemble.py index a1377ba..727c2c0 100644 --- a/docs/schemas/gen_ensemble.py +++ b/docs/schemas/gen_ensemble.py @@ -78,7 +78,6 @@ def path(d, cls, start=False, end=False): def draw(): dy = 205 - # Internet et bordures out.append(' ') text(750, 54, "Internet", "lbl", "middle") path("M750 76 V110", "net", start=True, end=True) @@ -89,19 +88,16 @@ def draw(): text(750, 214, "même IP et même MAC de gateway · sans état", "sub", "middle") text(750, 230, "VTEP · VNI 66001 (public)", "sub", "middle") - # Poste de l'opérateur group(1180, 20, 280, 100, "POSTE DE L'OPÉRATEUR") box(1200, 50, 240, 52, "Terraform / OpenTofu", ["provider two · #72"], "future") - text(1164, 150, "API publique de l'orchestrateur", "nett", "end") - text(1164, 166, "par Internet et les bordures (VNI 66001)", "nett", "end") + path("M1180 64 H900", "net", end=True) + text(1040, 56, "API publique de l'orchestrateur", "nett", "middle") - # Underlay A : routeurs group(40, 280, 480, 130, "CLUSTER A") box(60, 312, 210, 56, "routeur 1", ["169.254.0.1/28"]) box(290, 312, 210, 56, "routeur 2", ["169.254.0.2/28"]) text(280, 392, "VRRP · VTEP · VNI 66000 · NAT vers le VNI 66000 · #72", "sub", "middle") - # Underlay B group(1200, 280, 260, 130, "CLUSTER B") box(1215, 312, 110, 56, "routeur 1", ["169.254.0.1/28"]) box(1335, 312, 110, 56, "routeur 2", ["169.254.0.2/28"]) @@ -122,7 +118,6 @@ def draw(): text(1330, 765 + dy, "l'hyperviseur détaillé", "sub", "middle") path(f"M1452 460 V{395 + dy}", "link") - # eBGP path("M500 340 H1215", "link") text(860, 332, "eBGP · routeur 2 de A → routeur 1 de B", "sub", "middle") path("M660 240 V258 H210 V312", "link") @@ -130,7 +125,6 @@ def draw(): text(420, 252, "eBGP", "sub", "middle") text(1060, 252, "eBGP", "sub", "middle") - # Underlay A : bus, route reflector, services out.append(' ') text(690, 465, "underlay A · VXLAN UDP 4789 · BGP", "sub") path("M75 368 V460", "link") @@ -145,7 +139,6 @@ def draw(): path("M510 410 V546 H760", "orch", end=True) path("M1200 400 H1192 V560 H1180", "orch", end=True) - # Hyperviseur group(40, 395 + dy, 1120, 410, "HYPERVISEUR A (détaillé)") box(60, 430 + dy, 260, 52, "br-000000", ["IP de l'hyperviseur = VTEP"]) box(60, 496 + dy, 260, 52, "FRR · bgpd", ["sessions EVPN vers les RR"]) @@ -174,13 +167,13 @@ def draw(): out.append(f' VNI 66001') path(f"M300 {430 + dy} V460", "link") - # Orchestration : agent → routeurs de l'underlay A path(f"M320 {580 + dy} H332 V410", "orch", end=True) text(340, 596, "register · ordres · événements (mTLS, sortant)", "orcht") - path("M1180 76 H1172 V546 H1160", "net", end=True) + path("M750 240 V300 H1140 V520", "net", end=True) + text(1132, 430, "API publique", "nett", "end") + text(1132, 446, "VNI 66001", "nett", "end") - # Légende ly = 840 + dy path(f"M60 {ly} H110", "data") text(118, ly + 4, "plan de données : VXLAN") @@ -194,12 +187,12 @@ def draw(): text(922, ly + 4, "à venir (ticket indiqué)") notes = [ - "Les agents ne sont jamais joints par l'orchestrateur : ils se connectent au broker en sortie, via leur passerelle ; les routeurs de leur cluster les NAT vers le VNI 66000.", + "Les agents ne sont jamais joints par l'orchestrateur : ils se connectent au broker en sortie, via leur passerelle ; les routeurs de leur cluster les traduisent (NAT) vers le VNI 66000.", "L'orchestrateur a une patte dans le VNI 66001 : son API est joignable depuis Internet, par les bordures.", "VM publique : un subnet public dans son VPC, relié au subnet public de l'hôte (VNI 66001), dont la gateway anycast est portée par toutes les bordures.", "VM privée : route par défaut de type 5 vers la passerelle NAT de son VPC (IP de sortie du VPC) si le VPC autorise Internet, ou IP flottante 1:1 sur son hôte.", "Les bordures restent sans état : tout NAT vit sur un hyperviseur. Broker et orchestrateur sont des VM du VNI 66000, partagé : elles tournent sur les hyperviseurs de n'importe quel cluster.", - "Un route reflector par cluster : un événement d'un cluster ne coupe pas les deux sessions. Chaque lien routeurs ↔ RR est en 169.254.0.0/28, propre à son cluster.", + "Au moins un route reflector ; deux prévus, ici un par cluster : un événement d'un cluster ne coupe pas les deux sessions. Chaque lien routeurs ↔ RR est en 169.254.0.0/28, propre à son cluster.", ] for k, n in enumerate(notes): text(60, 884 + dy + k * 18, n) @@ -208,7 +201,7 @@ def draw(): def render(p): out.clear() draw() - head = f'' + head = f'' return "\n".join([head, style(p)] + out + ["", ""]) diff --git a/release_notes/0.2.0.md b/release_notes/0.2.0.md index f8031ef..91c55a5 100644 --- a/release_notes/0.2.0.md +++ b/release_notes/0.2.0.md @@ -136,6 +136,9 @@ L3VNI, avec une configuration BGP pilotée par l'agent ; documentation du projet - **Un fichier de configuration présent mais invalide fait désormais échouer le démarrage.** Jusqu'en 0.1.0 l'erreur de lecture était ignorée : l'agent tournait alors entièrement sur ses valeurs par défaut sans le dire, ce qui rendait indétectable une simple tabulation d'indentation +- **Réponses de l'API des subnets alignées sur la spécification** : `gateway` est rendu aussi par + `GET /subnets` et par la réponse 202 de `POST /subnets`, plus seulement par + `GET /subnets/{name}` ; `vxlan_id` est omis hors mode `vxlan` au lieu de valoir 0 (#80) - `probe` annonce explicitement `"served": false` pour une MAC non réservée, au lieu d'omettre le champ et de le rendre indistinguable d'une réponse tronquée - **Le serveur DHCP intégré s'arrête proprement** sur `SIGTERM` et `SIGINT` : il ferme sa socket de