Vue d’ensemble#

Cycle d’une requête#

HTTP → internal/api/agent → Dispatcher.Prepare() → Dispatcher.Dispatch() → worker.Queue → Command.Execute()
Prepare (synchrone, dans le handler HTTP)

valide l’état, écrit l’état initial (creating / deleting) en base, et retourne 202 ou une erreur.

Dispatch (asynchrone)

place la commande sur un canal bufferisé ; une goroutine worker appelle Execute. C’est Dispatch, et lui seul, qui marque la ressource en error si Execute échoue.

Execute

effectue le travail réseau (netns, netif, VXLAN, veth, bridge, DHCP), puis met l’état à running / deleted.

Paquets#

Chemin

Rôle

internal/api/agent

handlers HTTP de /vpcs, /subnets et /vms

internal/dispatcher/agent

interface Command (Prepare/Execute/Key) et commandes concrètes

internal/state

énumération des états, CanDelete/IsTransient, seul point d’écriture des états

internal/migration

migrations idempotentes jouées au démarrage de l’agent

internal/vpc, internal/subnet

création et suppression bas niveau (netns + netif)

internal/l3vni

routage d’un VPC par L3VNI : VRF, L3VNI, transit, configuration FRR, export des routes /24 et /32

internal/frr

génération des commandes FRR, seul point d’appel à vtysh

internal/sysctl

écriture sous /proc/sys, dans un netns si besoin

internal/netns

network namespaces : create/enter/delete/call

internal/netif

netlink : bridge, veth, vxlan, tap, routes, adresses

internal/ebtables, internal/iptables

wrappers dédiés ; ne pas appeler ces binaires ailleurs

internal/qemu, internal/qmp

lancement de QEMU et client QMP sur socket Unix

internal/vm

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

client D-Bus systemd

pkg/logger, pkg/prometheus

journalisation slog et serveur de métriques

Ajouter un type de ressource#

  1. ajouter les helpers KV dans pkg/db/kv si nécessaire ;

  2. définir Create<X> / Delete<X> dans un nouveau paquet internal/<x>/ ;

  3. ajouter Create<X>Command / Delete<X>Command dans internal/dispatcher/agent/, dont Key() qui retourne <x>/<name> et le contrôle state.CanDelete dans Delete<X>Command.Prepare ;

  4. ajouter les handlers HTTP dans internal/api/agent/ et les routes dans server.go.

Stubs de plateforme#

Les fichiers _linux.go portent l’implémentation netlink/netns réelle ; les _other.go correspondants retournent une erreur « not supported on this platform ». Tous les paquets compilent sur macOS, ce qui permet d’y tester la logique qui ne touche ni netlink ni netns.

Deux exceptions à connaître : les stubs de netns exécutent fn sans changer de namespace — netns.Call réussit donc hors Linux — et netif compile partout parce que netlink fournit une implémentation « unspecified ».