twoctl : CLI locale de gestion des hôtes, connexion SSH persistante #71

Open
opened 2026-10-17 15:29:41 +00:00 by nicolas.boufideline · 2 comments

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.

twoctl host connect [-H hv1,hv2 | -g prod | --all]
twoctl host disconnect [-H … | --all]
twoctl host list        # colonne « connexion » : up / down / périmée

connect lance pour chaque hôte un seul maître OpenSSH persistant, avec une socket de contrôle :

ssh -f -N -M -S ~/.cache/twoctl/run/<contexte>/hv1.ctl \
    -o ControlPersist=8h -o ServerAliveInterval=15 -o ExitOnForwardFailure=yes \
    -L ~/.cache/twoctl/run/<contexte>/hv1.api.sock:127.0.0.1:8080  hv1
  • Le tunnel aboutit à une socket Unix locale, pas à un port TCP : pas de conflit de port, et la socket est protégée par les droits du fichier.
  • Pas de tunnel en double : avant de lancer quoi que ce soit, connect vérifie l'état avec ssh -O check. Si les sockets sont périmées (maître mort), il les nettoie et recrée le tunnel.
  • disconnect envoie ssh -O exit et supprime les sockets.
  • Une commande lancée sans connexion échoue avec un message clair (hv1 : non connecté, lancer « twoctl host connect -H hv1 »). Pas de connexion implicite.
  • On utilise le binaire ssh système, pas une bibliothèque Go : il réutilise ~/.ssh/config, l'agent SSH, les clés matérielles, ProxyJump et known_hosts. Aucun démon propre à twoctl.
  • Délai d'inactivité par défaut : 8 h (ControlPersist), réglable, 0 = jusqu'au disconnect.

Configuration

twoctl config host add hv1 --address 192.168.14.11 [--user root] [--identity …] [--jump …] [--group prod]
twoctl config host rm hv1
twoctl config context list | use <nom> | current

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

twoctl host list | status [-H …|-g …]   # joignable, version de l'agent, backend DHCP, sessions BGP, alertes watchdog
twoctl vpc|subnet|vm list [-H …]        # vue agrégée : quelle ressource vit sur quel hôte
twoctl vpc|subnet|vm create|get|delete  # sur un hôte, une liste ou un groupe
  • Les opérations sur plusieurs hôtes s'exécutent en parallèle, avec un bilan par hôte. Pas d'atomicité : en cas d'échec partiel, la CLI le signale et affiche la commande pour rejouer ou nettoyer. Le rollback relève de l'orchestrateur.
  • Sortie en tableau par défaut, -o json pour 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 :

internal/agentapi/          types (VPC, Subnet, VM, Status…) + interface Agent, indépendante du transport
internal/agentapi/sshhttp/  transport de twoctl : HTTP sur la socket du tunnel SSH
internal/twoctl/            inventaire, contextes, tunnels SSH, rendu CLI
cmd/twoctl/                 main seulement
  • Les commandes ne voient que l'interface Agent, jamais HTTP ni SSH.
  • Les charges utiles sont celles de api/agent.yaml (source unique du contrat) ; l'orchestrateur réutilisera internal/agentapi avec son propre transport (broker).
  • internal/ : rien n'est importable hors du module two (pas de pkg/client).
  • Bibliothèque standard ou cobra pour la CLI, à trancher ; éviter une dépendance si possible.

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.yaml avant de l'envoyer — motifs (dev des disques ^[sv]d[a-z]$, sinon panic de l'agent ou options QEMU injectées dans -drive), plages (l3vni, VNI), formats (IPv4, CIDR, base64 de user_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

  • Tant qu'un tunnel est ouvert, tout processus de l'utilisateur local peut appeler l'API de l'agent : c'est un accès équivalent à root sur l'hyperviseur.
  • Mesures : répertoire run/ en 0700, sockets en 0600 ; ControlPersist à 8 h comme filet de sécurité ; host list affiche toujours les connexions ouvertes ; StrictHostKeyChecking jamais 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).
  • Exposer l'API de l'agent sur le réseau (TLS, authentification, droits) reste hors périmètre : cela ne se justifiera qu'avec l'orchestrateur.

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 de curl et jq.

Jalon

Après la 0.2.0, dans le même lot que #39.

## 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. ``` twoctl host connect [-H hv1,hv2 | -g prod | --all] twoctl host disconnect [-H … | --all] twoctl host list # colonne « connexion » : up / down / périmée ``` `connect` lance pour chaque hôte **un seul** maître OpenSSH persistant, avec une socket de contrôle : ``` ssh -f -N -M -S ~/.cache/twoctl/run/<contexte>/hv1.ctl \ -o ControlPersist=8h -o ServerAliveInterval=15 -o ExitOnForwardFailure=yes \ -L ~/.cache/twoctl/run/<contexte>/hv1.api.sock:127.0.0.1:8080 hv1 ``` - Le tunnel aboutit à une **socket Unix locale**, pas à un port TCP : pas de conflit de port, et la socket est protégée par les droits du fichier. - **Pas de tunnel en double** : avant de lancer quoi que ce soit, `connect` vérifie l'état avec `ssh -O check`. Si les sockets sont périmées (maître mort), il les nettoie et recrée le tunnel. - `disconnect` envoie `ssh -O exit` et supprime les sockets. - Une commande lancée sans connexion échoue avec un message clair (`hv1 : non connecté, lancer « twoctl host connect -H hv1 »`). Pas de connexion implicite. - On utilise le **binaire `ssh` système**, pas une bibliothèque Go : il réutilise `~/.ssh/config`, l'agent SSH, les clés matérielles, `ProxyJump` et `known_hosts`. Aucun démon propre à twoctl. - **Délai d'inactivité par défaut : 8 h** (`ControlPersist`), réglable, `0` = jusqu'au `disconnect`. ## Configuration ``` twoctl config host add hv1 --address 192.168.14.11 [--user root] [--identity …] [--jump …] [--group prod] twoctl config host rm hv1 twoctl config context list | use <nom> | current ``` 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 ``` twoctl host list | status [-H …|-g …] # joignable, version de l'agent, backend DHCP, sessions BGP, alertes watchdog twoctl vpc|subnet|vm list [-H …] # vue agrégée : quelle ressource vit sur quel hôte twoctl vpc|subnet|vm create|get|delete # sur un hôte, une liste ou un groupe ``` - Les opérations sur plusieurs hôtes s'exécutent en parallèle, avec un bilan par hôte. **Pas d'atomicité** : en cas d'échec partiel, la CLI le signale et affiche la commande pour rejouer ou nettoyer. Le rollback relève de l'orchestrateur. - Sortie en tableau par défaut, `-o json` pour 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 : ``` internal/agentapi/ types (VPC, Subnet, VM, Status…) + interface Agent, indépendante du transport internal/agentapi/sshhttp/ transport de twoctl : HTTP sur la socket du tunnel SSH internal/twoctl/ inventaire, contextes, tunnels SSH, rendu CLI cmd/twoctl/ main seulement ``` - Les commandes ne voient que l'interface `Agent`, jamais HTTP ni SSH. - Les charges utiles sont celles de `api/agent.yaml` (source unique du contrat) ; l'orchestrateur réutilisera `internal/agentapi` avec son propre transport (broker). - `internal/` : rien n'est importable hors du module two (pas de `pkg/client`). - Bibliothèque standard ou cobra pour la CLI, à trancher ; éviter une dépendance si possible. ## 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.yaml`** avant de l'envoyer — motifs (`dev` des disques `^[sv]d[a-z]$`, sinon panic de l'agent ou options QEMU injectées dans `-drive`), plages (`l3vni`, VNI), formats (IPv4, CIDR, base64 de `user_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 - Tant qu'un tunnel est ouvert, **tout processus de l'utilisateur local** peut appeler l'API de l'agent : c'est un accès équivalent à root sur l'hyperviseur. - Mesures : répertoire `run/` en 0700, sockets en 0600 ; `ControlPersist` à 8 h comme filet de sécurité ; `host list` affiche toujours les connexions ouvertes ; `StrictHostKeyChecking` jamais 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). - Exposer l'API de l'agent sur le réseau (TLS, authentification, droits) reste **hors périmètre** : cela ne se justifiera qu'avec l'orchestrateur. ## 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 de `curl` et `jq`. ## Jalon Après la 0.2.0, dans le même lot que #39.
Author
Owner

Attribution des MAC des VM (suite de #62)

Depuis #62, la MAC de chaque interface est fournie par l'appelant dans POST /vms (champ mac, 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

Type de subnet Domaine L2 Pool
vxlan le subnet (un bridge et un VNI par subnet ; EVPN tient une table de MAC par VNI) un pool par VPC
bridge bridge partagé de l'hôte, commun à tous les VPC et à tous les hôtes un pool unique pour toute l'infra
public_ip idem un pool unique pour toute l'infra
  • Un pool par VPC pour vxlan est 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.
  • Un même VPC peut mélanger les trois types : chaque type a son préfixe dédié, ce qui évite toute collision entre pools et indique le type de l'interface au diagnostic.
  • Dans une même VNI L2, deux VM vivantes avec la même MAC sur deux hôtes font « bouger » la MAC entre VTEP : FRR peut la geler (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 subnet vxlan (#57) ;
  • 02:02:<IPv4 du VTEP> : MAC de routeur L3VNI (#41) ;
  • 02:03:<IPv4 du VTEP> : bridge br-<subnet> dans le netns du VPC, subnets vxlan (porte l'adresse d'émission).

Les valeurs 0x01 à 0x0f du 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)

Type Préfixe Taille du pool
vxlan 02:10:xx:xx:xx:xx 32 bits par VPC
bridge 02:11:xx:xx:xx:xx 32 bits, infra entière
public_ip 02:12:xx:xx:xx:xx 32 bits, infra entière

Allocation et quarantaine

  • Ne pas précharger les pools : 2^32 lignes, c'est le problème de la table subnet/<nom>/dhcp/<ip> que #62 a retirée. La base ne garde que les MAC déjà attribuées.
  • Attribution : la plus ancienne MAC libérée dont la quarantaine est passée, sinon la suivante d'un compteur par pool.
  • Quarantaine : une MAC libérée n'est pas réattribuée avant un délai réglable (en minutes ou en heures). Elle laisse le temps aux caches ARP des autres VM, aux FDB des bridges (300 s par défaut) et aux annonces EVPN type 2 de disparaître.
  • Concurrence : contrainte d'unicité sur (pool, mac). Avec SQLite, la transaction d'attribution en BEGIN IMMEDIATE ; avec PostgreSQL (#72), SELECT … FOR UPDATE SKIP LOCKED.

Esquisse :

CREATE TABLE mac_pool (
  pool TEXT PRIMARY KEY,   -- 'vxlan:<vpc>', 'bridge', 'public_ip'
  prefix TEXT NOT NULL,
  next INTEGER NOT NULL DEFAULT 0
);
CREATE TABLE mac (
  pool TEXT NOT NULL REFERENCES mac_pool(pool),
  mac TEXT NOT NULL,
  vm TEXT,                 -- NULL = libre
  nic INTEGER,
  released_at TIMESTAMP,
  PRIMARY KEY (pool, mac)
);

-- réutilisation, sinon compteur
SELECT mac FROM mac
WHERE pool = :pool AND vm IS NULL AND released_at < :now - :quarantaine
ORDER BY released_at LIMIT 1;

Points ouverts

  • Une base SQLite par poste : deux opérateurs sur deux postes auraient deux tables, donc des doublons possibles. Il faut soit une seule base partagée, soit attendre l'orchestrateur pour le travail à plusieurs.
  • Reprise de l'existant : 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 MAC 00:22:33:<rang de l'IP>, hors des préfixes ci-dessus, donc sans collision avec les nouveaux pools.
## Attribution des MAC des VM (suite de #62) Depuis #62, la MAC de chaque interface est **fournie par l'appelant** dans `POST /vms` (champ `mac`, 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 | Type de subnet | Domaine L2 | Pool | |---|---|---| | `vxlan` | le subnet (un bridge et un VNI par subnet ; EVPN tient une table de MAC par VNI) | **un pool par VPC** | | `bridge` | bridge partagé de l'hôte, commun à tous les VPC et à tous les hôtes | **un pool unique pour toute l'infra** | | `public_ip` | idem | **un pool unique pour toute l'infra** | - Un pool par VPC pour `vxlan` est 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. - Un même VPC peut mélanger les trois types : chaque type a son **préfixe dédié**, ce qui évite toute collision entre pools et indique le type de l'interface au diagnostic. - Dans une même VNI L2, deux VM vivantes avec la même MAC sur deux hôtes font « bouger » la MAC entre VTEP : FRR peut la geler (`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 subnet `vxlan` (#57) ; - `02:02:<IPv4 du VTEP>` : MAC de routeur L3VNI (#41) ; - `02:03:<IPv4 du VTEP>` : bridge `br-<subnet>` dans le netns du VPC, subnets `vxlan` (porte l'adresse d'émission). Les valeurs `0x01` à `0x0f` du 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) | Type | Préfixe | Taille du pool | |---|---|---| | `vxlan` | `02:10:xx:xx:xx:xx` | 32 bits par VPC | | `bridge` | `02:11:xx:xx:xx:xx` | 32 bits, infra entière | | `public_ip` | `02:12:xx:xx:xx:xx` | 32 bits, infra entière | ### Allocation et quarantaine - **Ne pas précharger les pools** : 2^32 lignes, c'est le problème de la table `subnet/<nom>/dhcp/<ip>` que #62 a retirée. La base ne garde que les MAC déjà attribuées. - **Attribution** : la plus ancienne MAC libérée dont la quarantaine est passée, sinon la suivante d'un compteur par pool. - **Quarantaine** : une MAC libérée n'est pas réattribuée avant un délai réglable (en minutes ou en heures). Elle laisse le temps aux caches ARP des autres VM, aux FDB des bridges (300 s par défaut) et aux annonces EVPN type 2 de disparaître. - **Concurrence** : contrainte d'unicité sur `(pool, mac)`. Avec SQLite, la transaction d'attribution en `BEGIN IMMEDIATE` ; avec PostgreSQL (#72), `SELECT … FOR UPDATE SKIP LOCKED`. Esquisse : ```sql CREATE TABLE mac_pool ( pool TEXT PRIMARY KEY, -- 'vxlan:<vpc>', 'bridge', 'public_ip' prefix TEXT NOT NULL, next INTEGER NOT NULL DEFAULT 0 ); CREATE TABLE mac ( pool TEXT NOT NULL REFERENCES mac_pool(pool), mac TEXT NOT NULL, vm TEXT, -- NULL = libre nic INTEGER, released_at TIMESTAMP, PRIMARY KEY (pool, mac) ); -- réutilisation, sinon compteur SELECT mac FROM mac WHERE pool = :pool AND vm IS NULL AND released_at < :now - :quarantaine ORDER BY released_at LIMIT 1; ``` ### Points ouverts - **Une base SQLite par poste** : deux opérateurs sur deux postes auraient deux tables, donc des doublons possibles. Il faut soit une seule base partagée, soit attendre l'orchestrateur pour le travail à plusieurs. - **Reprise de l'existant** : `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 MAC `00:22:33:<rang de l'IP>`, hors des préfixes ci-dessus, donc sans collision avec les nouveaux pools.
Author
Owner

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

  • Base SQLite propre à twoctl, une par contexte et par poste (~/.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.
  • Un VPC est déclaré dans twoctl, puis créé sur un hôte quand on y place un subnet ou une VM.
  • Placement explicite : le formulaire de création d'une VM demande l'hôte (placement automatique : #72).
  • Création à la demande : VM placée sur un hôte où son VPC ou son subnet n'existe pas → twoctl crée VPC, subnet puis VM, dans cet ordre.
  • Nettoyage : dernière VM d'un subnet qui quitte un hôte → twoctl supprime le subnet sur cet hôte, puis le VPC s'il n'y porte plus rien (séquence orchestrée validée par 52).
  • Écarts base/agents (ressource en base absente de son hôte, ressource d'un agent inconnue de la base) signalés dans les vues, jamais réparés automatiquement en v1. Import : reprend dans la base ce que les agents portent déjà.
  • MAC en migration : la VM cible garde la MAC de la source (cas rendu sûr par #95).

Interfaces

Commandes en ligne (scripts, -o json) et TUI (twoctl sans argument ou twoctl ui), sur le même cœur (internal/agentapi, tunnels, validation). TUI en Bubble Tea (+ Bubbles, Lip Gloss), choisi pour la testabilité (Update pur) ; commandes en bibliothèque standard, sans cobra.

Vues :

  • au lancement : choix du contexte ;
  • menu à gauche : VPC (dépliable : liste des VPC), VMs, Hosts (dépliable : liste des hôtes) ;
  • VPC : liste + créer un VPC ; un VPC → ses subnets, créer un subnet, supprimer le VPC ; un subnet → le supprimer ;
  • VMs : nom, VPC, hôte, IP principale, IP publique (IP flottante si présente) ; créer une VM ;
  • Hosts : liste, ajouter un hôte, importer ce qui est absent de la base ; un hôte → ses informations à jour (/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, + interface Agent ; conformité au contrat vérifiée par la validation des réponses du mock — révisé le 2026-10-31 : oapi-codegen dé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)

  1. Mock de l'agent et parc de test en conteneurs (ajouté le 2026-10-31) : 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, /ping compris), 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.yaml est refusée et journalisée (le vrai agent, lui, fait confiance à son appelant). Injection d'écarts et de pannes à la demande (ressource en error, ressource disparue, agent injoignable). Conteneurs « hôtes » hv1 à hv3 (sshd + mock sur 127.0.0.1:8080) dans test/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.
  2. Socle et lecture : contextes, tunnels (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).
  3. Écriture : créations et suppressions avec validation locale selon api/agent.yaml, création à la demande, nettoyage, attribution des MAC (préfixes 02:10 vxlan par VPC, 02:11 bridge, 02:12 public_ip, quarantaine).

Lot 2 précisé (2026-11-01) :

  • Validation : twoctl embarque api/agent.yaml et valide chaque requête sortante avec kin-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.
  • Base d'abord : l'intention est écrite avant d'agir ; en cas d'échec sur un agent, elle reste, l'écart s'affiche, et relancer la même commande reprend l'opération (création à la demande idempotente).
  • VNI attribués par twoctl quand l'option est absente : L3VNI dans 2–65535 (hors 253–255), VNI de subnet à partir de 65536, premier libre dans la base du contexte ; --l3vni / --vxlan-id forcent une valeur, refusée si déjà prise.
  • Quarantaine des MAC : 1 h par défaut, réglable par contexte.
  • Commandes : 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 de running), 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

  • Tunnel ouvert = accès équivalent à root sur l'hyperviseur pour tout processus local : mesures du corps du ticket inchangées (run/ en 0700, sockets en 0600, ControlPersist, StrictHostKeyChecking jamais désactivé, aucun secret stocké).
  • La base ne contient ni clé ni secret ; elle reste en 0600. Base par poste : deux opérateurs sur un même contexte divergeraient (avertissement, #72).
  • Nouvelles dépendances (Bubble Tea, Bubbles, Lip Gloss, pilote SQLite ; kin-openapi pour 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.
## 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 - **Base SQLite propre à twoctl**, une par contexte et par poste (`~/.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. - **Un VPC est déclaré dans twoctl**, puis créé sur un hôte quand on y place un subnet ou une VM. - **Placement explicite** : le formulaire de création d'une VM demande l'hôte (placement automatique : #72). - **Création à la demande** : VM placée sur un hôte où son VPC ou son subnet n'existe pas → twoctl crée VPC, subnet puis VM, dans cet ordre. - **Nettoyage** : dernière VM d'un subnet qui quitte un hôte → twoctl supprime le subnet sur cet hôte, puis le VPC s'il n'y porte plus rien (séquence orchestrée validée par 52). - **Écarts base/agents** (ressource en base absente de son hôte, ressource d'un agent inconnue de la base) signalés dans les vues, jamais réparés automatiquement en v1. **Import** : reprend dans la base ce que les agents portent déjà. - **MAC en migration** : la VM cible garde la MAC de la source (cas rendu sûr par #95). ### Interfaces Commandes en ligne (scripts, `-o json`) **et** TUI (`twoctl` sans argument ou `twoctl ui`), sur le même cœur (`internal/agentapi`, tunnels, validation). TUI en **Bubble Tea** (+ Bubbles, Lip Gloss), choisi pour la testabilité (`Update` pur) ; commandes en bibliothèque standard, sans cobra. Vues : - **au lancement** : choix du contexte ; - **menu à gauche** : `VPC` (dépliable : liste des VPC), `VMs`, `Hosts` (dépliable : liste des hôtes) ; - **VPC** : liste + créer un VPC ; un VPC → ses subnets, créer un subnet, supprimer le VPC ; un subnet → le supprimer ; - **VMs** : nom, VPC, hôte, IP principale, IP publique (IP flottante si présente) ; créer une VM ; - **Hosts** : liste, ajouter un hôte, importer ce qui est absent de la base ; un hôte → ses informations à jour (`/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, + interface `Agent` ; conformité au contrat vérifiée par la validation des réponses du mock — révisé le 2026-10-31 : `oapi-codegen` dé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) 0. **Mock de l'agent et parc de test en conteneurs** (ajouté le 2026-10-31) : `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`, `/ping` compris), 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.yaml` est refusée et journalisée (le vrai agent, lui, fait confiance à son appelant). Injection d'écarts et de pannes à la demande (ressource en `error`, ressource disparue, agent injoignable). Conteneurs « hôtes » `hv1` à `hv3` (`sshd` + mock sur `127.0.0.1:8080`) dans `test/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. 1. **Socle et lecture** : contextes, tunnels (`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). 2. **Écriture** : créations et suppressions avec validation locale selon `api/agent.yaml`, création à la demande, nettoyage, attribution des MAC (préfixes `02:10` vxlan par VPC, `02:11` bridge, `02:12` public_ip, quarantaine). Lot 2 précisé (2026-11-01) : - **Validation** : twoctl embarque `api/agent.yaml` et valide chaque requête sortante avec `kin-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. - **Base d'abord** : l'intention est écrite avant d'agir ; en cas d'échec sur un agent, elle reste, l'écart s'affiche, et relancer la même commande reprend l'opération (création à la demande idempotente). - **VNI attribués par twoctl** quand l'option est absente : L3VNI dans 2–65535 (hors 253–255), VNI de subnet à partir de 65536, premier libre dans la base du contexte ; `--l3vni` / `--vxlan-id` forcent une valeur, refusée si déjà prise. - **Quarantaine des MAC** : 1 h par défaut, réglable par contexte. - Commandes : `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 de `running`), `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 - Tunnel ouvert = accès équivalent à root sur l'hyperviseur pour tout processus local : mesures du corps du ticket inchangées (`run/` en 0700, sockets en 0600, `ControlPersist`, `StrictHostKeyChecking` jamais désactivé, aucun secret stocké). - La base ne contient ni clé ni secret ; elle reste en 0600. Base par poste : deux opérateurs sur un même contexte divergeraient (avertissement, #72). - Nouvelles dépendances (Bubble Tea, Bubbles, Lip Gloss, pilote SQLite ; `kin-openapi` pour 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.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
syonad/two#71
No description provided.