Orchestrateur : agents reliés par un broker (register, ordres, événements), piloté par Terraform/OpenTofu #72

Open
opened 2026-10-17 15:53:27 +00:00 by nicolas.boufideline · 1 comment

Objectif

Concevoir l'orchestrateur de two et son lien avec les agents par un broker de messages (MQTT : Mosquitto, et/ou RabbitMQ avec son plugin MQTT). L'orchestrateur est piloté par Terraform / OpenTofu (provider dédié) ; twoctl (#71) continue de parler directement aux agents par tunnel SSH.

Ce ticket porte la conception. L'implémentation sera découpée ensuite.

Modèle

Les agents ouvrent la connexion vers le broker (sortante uniquement, aucun port à ouvrir sur les hyperviseurs) :

File / topic Sens Contenu
register agent → orchestrateur annonce de l'agent : identité, version, capacités, connaissance de l'hôte (#39)
ordres (une par agent) orchestrateur → agent création/suppression de VPC, subnets, VM…
événements (unique) agents → orchestrateur notifications du watchdog, changements d'état des ressources
  • Les charges utiles sont celles de api/agent.yaml : un ordre est le même JSON qu'un POST de l'API locale. Le contrat reste unique (documentation des files possible en AsyncAPI, qui réutilise les schémas OpenAPI).
  • Le modèle est déjà asynchrone (202 + suivi d'état) : « créer » devient « publier l'ordre », le suivi passe par les événements.
  • Côté code : l'orchestrateur réutilise internal/agentapi (#71) avec un transport broker.

Frontière de confiance

L'agent fait confiance à son appelant et ne valide pas ses entrées. Avec un broker, quiconque peut publier dans la file d'ordres d'un agent contrôle l'hyperviseur : le broker devient la frontière de confiance.

  • Identité par agent : certificat client (mTLS) ; enregistrement sur register authentifié, sinon n'importe quel hôte peut s'inscrire et recevoir des ordres et des données (user_data des VM, clés).
  • ACL par topic : un agent ne lit que ses ordres, n'écrit que sur register et les événements ; seul l'orchestrateur publie des ordres.
  • Ordres identifiés (idempotence, rejeu) ; signature des ordres à étudier si le broker ne suffit pas comme frontière.
  • Validation : l'orchestrateur (et le provider Terraform/OpenTofu) valide chaque ordre selon api/agent.yaml avant publication, comme twoctl.

Points à trancher

  • Mosquitto ou RabbitMQ (ACL par topic et mTLS possibles dans les deux) ; QoS et persistance des ordres si un agent est déconnecté.
  • Coexistence avec twoctl : des ressources peuvent être créées directement sur un agent. L'orchestrateur doit les voir (événements, état remonté) et décider : adoption, signalement de dérive, ou interdiction.
  • API de l'orchestrateur pour le provider Terraform/OpenTofu : forme, authentification, état.
  • Source de vérité : orchestrateur (état désiré) contre agents (état réel), réconciliation.
  • Ce qui reste exposé localement sur l'agent (API HTTP sur 127.0.0.1 pour twoctl).

Liens

#71 (twoctl, internal/agentapi), #39 (connaissance de l'hôte), #44 (Web UI).

## Objectif Concevoir l'orchestrateur de two et son lien avec les agents par un **broker de messages** (MQTT : Mosquitto, et/ou RabbitMQ avec son plugin MQTT). L'orchestrateur est piloté par **Terraform / OpenTofu** (provider dédié) ; **twoctl (#71) continue de parler directement aux agents** par tunnel SSH. Ce ticket porte la conception. L'implémentation sera découpée ensuite. ## Modèle Les agents ouvrent la connexion vers le broker (sortante uniquement, aucun port à ouvrir sur les hyperviseurs) : | File / topic | Sens | Contenu | |---|---|---| | `register` | agent → orchestrateur | annonce de l'agent : identité, version, capacités, connaissance de l'hôte (#39) | | ordres (une par agent) | orchestrateur → agent | création/suppression de VPC, subnets, VM… | | événements (unique) | agents → orchestrateur | notifications du watchdog, changements d'état des ressources | - Les **charges utiles sont celles de `api/agent.yaml`** : un ordre est le même JSON qu'un POST de l'API locale. Le contrat reste unique (documentation des files possible en AsyncAPI, qui réutilise les schémas OpenAPI). - Le modèle est déjà asynchrone (202 + suivi d'état) : « créer » devient « publier l'ordre », le suivi passe par les événements. - Côté code : l'orchestrateur réutilise `internal/agentapi` (#71) avec un transport broker. ## Frontière de confiance L'agent **fait confiance à son appelant** et ne valide pas ses entrées. Avec un broker, **quiconque peut publier dans la file d'ordres d'un agent contrôle l'hyperviseur** : le broker devient la frontière de confiance. - **Identité par agent** : certificat client (mTLS) ; enregistrement sur `register` authentifié, sinon n'importe quel hôte peut s'inscrire et recevoir des ordres et des données (`user_data` des VM, clés). - **ACL par topic** : un agent ne lit que *ses* ordres, n'écrit que sur `register` et les événements ; seul l'orchestrateur publie des ordres. - **Ordres identifiés** (idempotence, rejeu) ; signature des ordres à étudier si le broker ne suffit pas comme frontière. - **Validation** : l'orchestrateur (et le provider Terraform/OpenTofu) valide chaque ordre selon `api/agent.yaml` avant publication, comme twoctl. ## Points à trancher - Mosquitto ou RabbitMQ (ACL par topic et mTLS possibles dans les deux) ; QoS et persistance des ordres si un agent est déconnecté. - **Coexistence avec twoctl** : des ressources peuvent être créées directement sur un agent. L'orchestrateur doit les voir (événements, état remonté) et décider : adoption, signalement de dérive, ou interdiction. - API de l'orchestrateur pour le provider Terraform/OpenTofu : forme, authentification, état. - Source de vérité : orchestrateur (état désiré) contre agents (état réel), réconciliation. - Ce qui reste exposé localement sur l'agent (API HTTP sur `127.0.0.1` pour twoctl). ## Liens #71 (twoctl, `internal/agentapi`), #39 (connaissance de l'hôte), #44 (Web UI).
Author
Owner

Passerelles NAT des VPC : placement et bascule (2026-10-25)

Décidé sur #42 : l'orchestrateur place la passerelle NAT de chaque VPC qui autorise Internet, et la replace sur un autre hôte quand le sien est perdu (N1), par l'API de l'agent. L'agent ne détecte aucune panne. Avant l'orchestrateur, ce replacement est fait à la main via twoctl (#71).

## Passerelles NAT des VPC : placement et bascule (2026-10-25) Décidé sur #42 : l'orchestrateur **place** la passerelle NAT de chaque VPC qui autorise Internet, et la **replace** sur un autre hôte quand le sien est perdu (N1), par l'API de l'agent. L'agent ne détecte aucune panne. Avant l'orchestrateur, ce replacement est fait à la main via twoctl (#71).
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#72
No description provided.