Audit doc ↔ code et revue de #70 : commandes et API fausses dans la doc, faux positifs e2e #80
Labels
No labels
bug fix
feature implementation
new feature
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
syonad/two#80
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Contexte
Deux analyses menées le 2026-10-18 sur
main(3c3e58a) :docs/,api/agent.yaml, schémas, confrontés au code actuel ;f-70:(0932f5d→683e0fe), doc, générateurs de schémas, scripts e2e.Rien de bloquant côté code livré. Les conventions sont respectées (commits signés, préfixe
f-70:, VPC au masculin dans la doc). Les SVG sont identiques octet pour octet à la sortie degen_ensemble.py/gen_cluster.py. La matrice delab.rstcorrespond àrun.sh --matrice.Non vérifié : build Sphinx strict et shellcheck (absents du poste), aucun scénario e2e lancé (lab éteint).
Décisions à prendre
conf/agent/config.exemple.yml:67,configuration.rst:150etdiagnostic.rst:151donnent/run/two/vms/efi; le défaut du code est/run/two/vms/uefi(internal/config/agent/struct.go:83). Aligner la doc ou le code.architecture-cluster.rst:47-52etgen_ensemble.py:202disent « un par cluster » ;route-reflector.rst:6,routeurs.rst:21etgen_cluster.py:48disent « deux ». Trancher, puis régénérer les SVG.gatewayetvxlan_iddans l'API : corriger le code ou la spec (voir A-M13).lab.rst:79-80dit « sans préemption », alors que la campagne (lab.rst:406-407) et72-perte-switch.shconstatent que sw1 (priorité 200) redevient maître à son retour. Décrire le comportement réel ou désactiver la préemption ; en attendant, ne pas écrire « sans préemption » ailleurs (cf. A-M9).A. Doc ↔ code
Haute
docs/deploiement:route-reflector.rst:85-93cite « 30 s / 90 s », « 31 s » (s6-rr-loss du 2026-10-04) — contraire à la règle (résultats de lab dansdocs/developpement). Le passage est en plus périmé : « un seul RR, redondance non qualifiée », alors que #54 est fermé, que 71-perte-rr existe et que la campagne du 2026-10-13 a perdu 0 requête sur 510 (lab.rst:581). Réécrire sans chiffres : sansgraceful-restart, la perte de tous les RR coupe les tunnels, d'où deux RR jamais sur le même hôte.README.md:31:-Vne désactive pas la vérification (scripts/deploy.sh:340, booléen shflags à true par défaut) ; c'est--noverify(ce que dit déjàinstallation.rst:61).-b(README.md:26,installation.rst:35-37) : elle ne sert qu'à l'auto-mise à jour du script et au bootstrap, les binaires viennent toujours d'une release. Défautmain/,/final obligatoire : l'URL est concaténée sans séparateur (deploy.sh:330,:349),-b devdonne…/branch/devscripts/….br-sn000001(premier-vpc.rst:17,services.rst:33-34et:68-70,observabilite.rst:75-76) : le nom réel estbr-000001(internal/subnet/data.go:31-32,br-+ ce qui suit le premier tiret). Les commandessystemctl/tail/journalctlvisent des units inexistantes. Dans le mermaid, le bridge porte.253(émission), la gateway.254est sur le macvlangw-000001.creating(premier-vpc.rst:46-47,exploitation/api-agent/asynchronisme.rst:51-53) : présenté comme refusé en 422. Prepare accepte un VPC encreatingourunning(dispatcher/agent/subnet_commands.go:58), Execute attendrunningdans la limite dedispatcher.timeout_seconds(:83-102). 422 seulement si le parent est absent, enerrorou endeleting.asynchronisme.rst:69: uniface_typeinconnu ne donne pas 400, il retombe surdefault_interface(subnet_commands.go:62-65). Manquent en 400 : CIDR de VPC invalide,l3vnihors plage,interface_ipabsent (bridge/public_ip) ou fourni (vxlan), nombre deprimary≠ 1. En 422 :modeinconnu, CIDR vxlan invalide ou < /29, IP de VM hors CIDR ou réservée. En 409 :l3vnidéjà utilisée, oul3vnisans sectionbgp.diagnostic.rst:117:curl …/latest/meta-data/renvoie 404 ; le serveur ne sert que/meta-data,/user-data,/network-config,/vendor-data(internal/metadata/server.go:58-69).observabilite.rst:85:/opt/two/bin/db -conf …sans sous-commande n'affiche que l'usage (cmd/db/main.go:140), etdbn'est ni publié (release-pipeline.yml:51-54) ni déployé (deploy.sh:127). Documentergo build ./cmd/dbpuis./db -conf … print, ou livrer le binaire.premier-vpc.rst:132-136:ssh« depuis l'host » impossible sur un subnet vxlan (la note l.140 le dit elle-même). Passer parip netns exec vp-admin ssh ….Moyenne
dhcpabsent du README (README.md:38,:72-80) : « trois binaires » → quatre ; « les deux autres-conf» → les trois autres.br-publicen dur (internal/vpc/create.go:30-40, vethvp-<id>-e↔vp-<id>-i) alors queinstallation.rst:50-52etconcepts/vpc-subnet-vm.rst:15-21présentent-Pcomme libre : avec un autre nom, toute création de VPC échoue. Documenter le veth et la contrainte, ou rendre le nom configurable.concepts/modes-reseau.rst:128-133,:143,:156) : la route par défaut ne va qu'à l'interfaceprimary(internal/vm/create.go:138) ; en modebridge, la route du CIDR du VPC n'est pas annoncée (internal/subnet/routing.go).user_datavide ≠ absent (concepts/metadata-cloud-init.rst:23-30,diagnostic.rst:134-135) : faux, unuser_datavide équivaut à absent (internal/api/agent/vms.go:130-133) ; seuluser-dataest fourni par l'appelant, les autres documents viennent toujours de leur template. La spec (api/agent.yaml:506) est juste.configuration.rst:229-233,observabilite.rst:34-36) : défautenabled: false(struct.go:86).CLAUDE.mdabsent (architecture/index.rst:5-6,architecture/contraintes.rst:7-10) : le fichier n'est pas dans le dépôt et ne l'a jamais été. Retirer les deux mentions.architecture/vue-densemble.rst:26-76: le tableau des paquets n'a pasinternal/dhcpd,internal/dhcpbackend,internal/api/dhcp,internal/client/dhcp,pkg/db/statefile,internal/watchdog/notify.routeurs.rst:62-65et:76-78,route-reflector.rst:8,lab.rst:19-20) : #54 est fermé (VRRP v3 sur sw1/sw2, rr1/rr2, test 72). Formulation de la préemption selon D4.concepts/vpc-subnet-vm.rst:100-101: clévm/<name>/subnetpérimée →vm/<name>/nic/<i>/subnet(vm_commands.go:55,migration/nic.go:16).vpc-subnet-vm.rst:108-109: le motifvp-…est présenté comme validé par l'API ;postVpcne vérifie quenameetcidr(vpcs.go:58-80). Écrire que l'API ne valide aucun nommage, mais qu'un nom de VPC ou de subnet doit contenir un « - » (l'identifiant système est ce qui suit le premier tiret).api/agent.yamlvs code ::439:vxlan_id« present only when vxlan », mais toujours renvoyé (0 hors vxlan), faute d'omitempty(models.go:32) — D3 ;:461:gatewayn'est rempli que parGET /subnets/{name}, absent deGET /subnetset du 202 de POST (subnets.go:43-60,:121-141) — plutôt un défaut de code, D3 ;:48: le 400 dePOST /vpcsne mentionne pas le CIDR invalide ;:361: aucunpatternsur le nom de subnet, alors qu'un nom sans « - » fait paniquer le worker (subnet/data.go:31,SplitN(...)[1]). Ajouterpattern: '^[^-]+-.+'; la validation elle-même relève de l'appelant (twoctl / orchestrateur) ;:485: pas demaxItems, alors qu'une VM accepte au plus 27 interfaces (qemu/start_linux.go:15).diagnostic.rst:52:| jq .leasemasque"served": false, l'indice recherché →jq '{served, lease}'.installation.rst:34:-tprend la dernière release préversions comprises (aujourd'hui 0.2.0rc008), à préciser.Basse
README.md:52,premier-vpc.rst:59:vxlan_id: 1tombe dans la plage réservée aux L3VNI (vpc-subnet-vm.rst:32) ; prendre 65537.concepts/cycle-de-vie.rst:13: la transitionrunning → errorn'existe pas ;errorn'est posé que par l'échec d'Execute ou par la migration.api/agent.yaml:4-5: version 0.1.0, description sans les VM.docs/index.rst:20,docs/conf.py:14-15: « livré (0.1.0) », release'0.1.0'; à basculer au tag 0.2.0.services.rst:4: les units ne sont pas sous/opt/two/bin, seuls les binaires y sont.asynchronisme.rst:81: 405 non documentés ;/vpcset/subnetsles renvoient entext/plain,/vmsen JSON.lab.rst:7,:72,:89: « le route reflector » au singulier.premier-hyperviseur.rst:84,:96: renvoi à 0.2.0rc003 et « à trancher dans #51 », #51 est fermé.docs/README.md:17: le build local n'a pas-W --keep-goingcomme la CI (docs.yml:76).README.md:61vspremier-vpc.rst:97: chemins de disque d'exemple différents.test/e2e/build.sh:13: l'aide parle de « release de la topologie », la release est désormais fixée dansprovision/hypervisor.sh.B. Revue de #70
Important
run.shinopérante (0932f5d,test/e2e/run.sh:69,75,lib/fixture.sh:78-79) :finish_testajoute toujours deuxRÉUSSI(teardown,assert_clean), doncpassed -gt 0ne détecte plus un scénario dont aucun check propre n'a tourné (erreur bash dans le fichier sourcé,onmuet). Releverpassedavantfinish_test.suite/01-lab.sh:23(432b582) :check "…backend DHCP…" grep … | grep -qx …— le pipe s'applique à la sortie decheck, la ligne RÉUSSI/ÉCHOUÉ est avalée, le contrôle ne compte jamais. →check "…" sh -c "grep -A1 -x 'dhcp:' /etc/two/agent.yml | grep -qx ' backend: ${BACKEND}'".9e08b69,lab.rst:258) :TWO_IMAGEn'est construite que partwo_image, appelé seulement dans01-lab.sh;vm_create/vm_launch(lib/vm.sh),11-validation.sh,12-etats.shfont uncpsans la créer.run.sh 21échoue tant que 01 n'a pas tourné. →[ -f "${TWO_IMAGE}" ] || two_imagedanslib/vm.sh.fa42096/eeb77c3,gen_cluster.py:18,29) :vxlan-<vni>est dessiné dans lebr-<subnet>du netns du VPC. Le code crée deux bridgesbr-<id>(internal/subnet/create.go:145-165) : un dans le netns racine (vxlan +v-<id>-e), un dans le netns du VPC (v-<id>-i,gw-, tap). Ajouter le bridge côté hôte et le veth qui traverse la frontière.Mineur — réseau, doc et schémas
86923ea,architecture-cluster.rst:27,47) : préciser que lebgp listen rangedes RR doit couvrir l'underlay des deux clusters (aujourd'huirr1.confn'accepte que192.168.14.0/24), et que chaque cluster a un ASN de routeurs distinct (AS 65100 « valeur de production » vaut par cluster). Dépend de D2.gen_cluster.py:47,62: « AS 65000 » et « iBGP AS 64600 » côte à côte sans lelocal-as 64600 no-prepend replace-as(route-reflector.rst:76).gen_ensemble.py:181: la flèche du poste opérateur va directement à l'orchestrateur, alors que le texte dit « par Internet et les bordures (VNI 66001) », et croise les deux liens eBGP.architecture-cluster.rst:82,114: « du route reflector », « le route reflector qui les fait converger » au singulier.aria-labeldegen_cluster.py:93(« Architecture du cluster… ») ≠ alt RST (« Détail d'un cluster… ») ;gen_ensemble.py:210« routeurs du cluster » au singulier.architecture-cluster.rst:44+ note degen_ensemble.py: « les NAT » employé comme verbe → « les traduisent (NAT) ».Mineur — conventions
gen_ensemble.py:81,91,97,104…: ~9 commentaires de section, contraires à la convention (gen_cluster.pyn'en a aucun).suite/12-etats.sh:40-41: VPC au féminin (« vp-t12a supprimée », « recréée »).Mineur — scripts e2e
lib/core.sh:62:wait_state … deletedréussit si l'API est injoignable (curl -fvide = supprimé) ; même faux positif dansteardown_owned/delete_owned. Distinguer 404 et échec de connexion viaapi_code.lib/evpn.sh:82-94,130-134: les*_quietréussissent sijournalctléchoue ; sans 2ᵉ argument,watchdog_quietéchoue toujours (latent).33-bridge.sh:24,23-metadonnees.sh:25,28,33-34: tests négatifs fondés sur une sortie vide devm_ssh/curl; un SSH en panne les fait passer (contraire àlab.rst:464). Vérifier d'abord le succès de la commande.assert_clean:/tmp/t21-*2.log,/tmp/t22-*.log,/tmp/t44.log,/tmp/t72.*,/var/tmp/e2e/t61.*jamais supprimés ; netnst02-ebtnon nettoyé avant recréation (02-prerequis.sh:22).4e4ad7f) :71-perte-rr.sh:61-65ne vérifie pas le volume de requêtes émises etEND{print n,max}n'a pas de+0(aligner sur61-redemarrage-agent.sh:69) ;72-perte-switch.sh:41-45coupe l'underlay de sw2 même si l'état VRRP est illisible.run.sh:104:run.sh 4lance silencieusement le seul 41 ;run.sh dhcp-tworefusé alors que l'usage etlab.rst:242annoncent « par nom ». Exiger deux chiffres ou le nom exact.lab.rst:435: la liste decore.shometknown_flaky;:455-463, l'exemple vise une cible inexistante (10.98.1.10), contraire à la règle « la cible est vivante ».Note sans action :
eeb77c3mélange l'ajout des générateurs et la passe « VPC au masculin ».Ordre proposé
Campagne de lab du 2026-10-24 —
feature-80(5f5a179+ scénario 72, commités depuis en291ebf9et76d8169)Serveur EM-B420E-NVME fr-par-1, suite complète
run.sh --continue all, 13:37 → 14:40.Points de #80 validés en lab :
runen échec sur le seul échec réel.98_network_updates.cfgsous cloud-init 22.4 (Debian 12) : sans effet indésirable (03, 25, 27 verts).sw2 rétabli → sw1 reste maître (préemption désactivée), plus long silence 0,2 s ; session EVPN vers
10.255.255.2 jamais coupée (246 réponses pour 260 requêtes sur tout le scénario).
Échec de 12-etats — défaut de two, hors #80 : la VM
t12-errest démarrée sur un disque absent ;QEMU échoue (
Could not open '/var/lib/two/volumes/t12-absent.qcow2') après avoir créé/run/two/vms/monitor/t12-err.sock. La VM passe enerror, sa suppression aboutit (DELETE 202 puis 404),mais le socket reste :
assert_cleanle relève sur hv1. Ticket à part.Fusionné dans main (
c628e70), après la campagne de lab du 2026-10-24 (bilan ci-dessus). Échec 12-etats hors périmètre : #84.