twoctl : CLI locale de gestion des hôtes, connexion SSH persistante #71
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#71
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?
Objectif
Une CLI locale (Mac/Linux),
twoctl, pour paramétrer les hyperviseurs et gérer leurs ressources depuis le poste de l'opérateur, avant l'orchestrateur. Les types et l'interface d'API écrits pour twoctl (internal/agentapi) seront réutilisés par l'orchestrateur, avec son propre transport.Transport : tunnel SSH persistant
L'API de l'agent reste sur
127.0.0.1:8080, sans authentification ; aucune modification de l'agent n'est nécessaire.connectlance pour chaque hôte un seul maître OpenSSH persistant, avec une socket de contrôle :connectvérifie l'état avecssh -O check. Si les sockets sont périmées (maître mort), il les nettoie et recrée le tunnel.disconnectenvoiessh -O exitet supprime les sockets.hv1 : non connecté, lancer « twoctl host connect -H hv1 »). Pas de connexion implicite.sshsystème, pas une bibliothèque Go : il réutilise~/.ssh/config, l'agent SSH, les clés matérielles,ProxyJumpetknown_hosts. Aucun démon propre à twoctl.ControlPersist), réglable,0= jusqu'audisconnect.Configuration
Un fichier par contexte (
~/.config/twoctl/contexts/<nom>.yml), le contexte courant dans~/.config/twoctl/current. Les sockets sont rangées par contexte, ce qui permet d'avoir le lab et la prod connectés en même temps sans mélange.Commandes de la v1
-o jsonpour les scripts.Code
twoctl parle toujours directement aux agents ; l'orchestrateur futur (broker, piloté par Terraform/OpenTofu) est un autre appelant. Le code est rangé pour que les deux partagent le contrat sans exposer d'API Go publique :
Agent, jamais HTTP ni SSH.api/agent.yaml(source unique du contrat) ; l'orchestrateur réutiliserainternal/agentapiavec son propre transport (broker).internal/: rien n'est importable hors du module two (pas depkg/client).Validation des entrées
L'agent fait confiance à son appelant : il ne sera jamais exposé à un client libre, et beaucoup de champs de l'API n'y sont pas validés, par choix. twoctl est le premier appelant : c'est à lui de valider chaque requête selon le contrat
api/agent.yamlavant de l'envoyer — motifs (devdes disques^[sv]d[a-z]$, sinon panic de l'agent ou options QEMU injectées dans-drive), plages (l3vni, VNI), formats (IPv4, CIDR, base64 deuser_data), noms utilisables comme clés et noms d'interface. Une requête invalide est refusée localement, sans appel à l'agent. La même règle vaudra pour l'orchestrateur.Analyse de risque
run/en 0700, sockets en 0600 ;ControlPersistà 8 h comme filet de sécurité ;host listaffiche toujours les connexions ouvertes ;StrictHostKeyCheckingjamais désactivé ; aucune clé ni aucun secret stocké par twoctl (il s'appuie sur l'agent SSH, avec une clé dédiée recommandée).Hors v1
Montée de version de l'agent, push de configuration, placement automatique ;
host info(CPU, RAM, disques) attend #39. À terme, la suite e2e pourra passer par twoctl au lieu decurletjq.Jalon
Après la 0.2.0, dans le même lot que #39.
Attribution des MAC des VM (suite de #62)
Depuis #62, la MAC de chaque interface est fournie par l'appelant dans
POST /vms(champmac, obligatoire). L'agent la passe telle quelle à QEMU et à la réservation DHCP, sans en vérifier ni le format ni l'unicité. C'est donc twoctl qui attribue les MAC et en garantit l'unicité, avec une base SQLite locale. L'orchestrateur (#72) reprendra la même logique sur PostgreSQL.Où une MAC doit être unique
vxlanbridgepublic_ipvxlanest plus strict que nécessaire (un pool par subnet suffirait), mais il garantit en plus que deux NIC d'une même VM n'ont jamais la même MAC.dup-addr-detection). Le pool par VPC l'évite.MAC réservées par two
two fabrique ses propres MAC en
02:<rôle>:…(internal/netif/mac.go) :02:01:00:<VNI>: gateway anycast d'un subnetvxlan(#57) ;02:02:<IPv4 du VTEP>: MAC de routeur L3VNI (#41) ;02:03:<IPv4 du VTEP>: bridgebr-<subnet>dans le netns du VPC, subnetsvxlan(porte l'adresse d'émission).Les valeurs
0x01à0x0fdu deuxième octet sont réservées à two. Une MAC attribuée doit aussi être unicast (bit de poids faible du premier octet à 0).Préfixes proposés (à confirmer)
vxlan02:10:xx:xx:xx:xxbridge02:11:xx:xx:xx:xxpublic_ip02:12:xx:xx:xx:xxAllocation et quarantaine
subnet/<nom>/dhcp/<ip>que #62 a retirée. La base ne garde que les MAC déjà attribuées.(pool, mac). Avec SQLite, la transaction d'attribution enBEGIN IMMEDIATE; avec PostgreSQL (#72),SELECT … FOR UPDATE SKIP LOCKED.Esquisse :
Points ouverts
GET /vms/{name}rend désormais la MAC de chaque interface, ce qui permet à twoctl d'importer ou de rapprocher les MAC déjà en service. Les VM d'avant #62 gardent leurs MAC00:22:33:<rang de l'IP>, hors des préfixes ci-dessus, donc sans collision avec les nouveaux pools.Plan validé (2026-10-31)
Complète le corps du ticket et le commentaire sur les MAC. Ce qui change : twoctl a sa propre base (état voulu), une TUI en plus des commandes, et il crée et nettoie les ressources sur les hôtes à la demande.
Modèle
~/.local/share/twoctl/<contexte>.db) : hôtes, VPC, subnets, VM, MAC. Elle décrit ce qui doit exister ; les agents sont interrogés pour comparer. La configuration du contexte (hôtes, utilisateur SSH, rebond) reste dans~/.config/twoctl/. Un seul opérateur par contexte (avertissement dans la doc) ; le travail à plusieurs attend #72.Interfaces
Commandes en ligne (scripts,
-o json) et TUI (twoctlsans argument outwoctl ui), sur le même cœur (internal/agentapi, tunnels, validation). TUI en Bubble Tea (+ Bubbles, Lip Gloss), choisi pour la testabilité (Updatepur) ; commandes en bibliothèque standard, sans cobra.Vues :
VPC(dépliable : liste des VPC),VMs,Hosts(dépliable : liste des hôtes) ;/register,/ping, #39).Code
internal/agentapi(modèles JSON partagés : ceux de l'agent, déplacés dans ce paquet sans dépendance et utilisés par l'agent, le mock et twoctl, + interfaceAgent; conformité au contrat vérifiée par la validation des réponses du mock — révisé le 2026-10-31 :oapi-codegendéclare OpenAPI 3.1 non supporté et rend tous les champs de réponse optionnels),internal/agentapi/sshhttp(HTTP sur la socket du tunnel),internal/twoctl(contextes, base, tunnels, réconciliation, vues),cmd/twoctl(main seulement).Lots (0.3.0)
cmd/agent-kvm-mock(nommé par type d’agent : d’autres agents viendront), non livré dans les releases. Ressources en mémoire, mêmes routes que l'agent (/register,/pingcompris), mêmes états asynchrones (creating→running,deleting→ disparition) avec délais courts par défaut, réglables pour rejouer les délais réels, mêmes refus (409, 404…). Strict sur le contrat : toute requête non conforme àapi/agent.yamlest refusée et journalisée (le vrai agent, lui, fait confiance à son appelant). Injection d'écarts et de pannes à la demande (ressource enerror, ressource disparue, agent injoignable). Conteneurs « hôtes »hv1àhv3(sshd+ mock sur127.0.0.1:8080) danstest/twoctl/(compose, Dockerfile, script de lancement) : twoctl s'y connecte par son vrai chemin (tunnel SSH persistant, socket Unix,known_hosts, clé dédiée). Sert aux tests automatiques de twoctl et aux essais manuels de la TUI.host connect/disconnect/list/status), base SQLite, import, lecture de toutes les ressources (dont passerelles NAT et IP flottantes, pour l'IP publique des VM), TUI et commandes en lecture seule (boutons d'action affichés inactifs).api/agent.yaml, création à la demande, nettoyage, attribution des MAC (préfixes02:10vxlan par VPC,02:11bridge,02:12public_ip, quarantaine).Lot 2 précisé (2026-11-01) :
api/agent.yamlet valide chaque requête sortante aveckin-openapi(le validateur du mock, partagé) ; les règles hors schéma (IP dans le CIDR et hors adresses réservées, unicité des IP et des MAC) sont vérifiées en Go sur la base.--l3vni/--vxlan-idforcent une valeur, refusée si déjà prise.vpc create/delete,subnet create/delete(base seulement ; suppression refusée tant qu'une VM ou une passerelle s'en sert),vm create --host … --nic <subnet>=<ip> --disk <dev>=<chemin>(création à la demande VPC → subnet → VM, attente derunning),vm delete(puis nettoyage du subnet et du VPC sur l'hôte, ordre du test 52),natgw create/delete,fip create/delete. TUI : boutons actifs, formulaires, confirmation de chaque suppression, ajout d'hôte.Hors v1 : placement automatique, réparation des écarts, montée de version de l'agent, e2e via twoctl.
Risques
run/en 0700, sockets en 0600,ControlPersist,StrictHostKeyCheckingjamais désactivé, aucun secret stocké).kin-openapipour le mock seulement) : versions épinglées et relues ; pilote SQLite en Go pur de préférence, pour garder la compilation croisée sans cgo.