A simple but powerful orchestrator, designed to be easy to use and API-first.
  • Go 75.1%
  • Shell 24.9%
Find a file
GnomeZworc dd9844284d
f-81: api: default_route sans gateway réservé au mode bridge #81
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
2026-10-25 11:53:33 +01:00
.forgejo/workflows ci: docs: liens du menu de version relatifs à switcher.json 2026-10-25 11:29:38 +01:00
api f-81: api: default_route sans gateway réservé au mode bridge #81 2026-10-25 11:53:33 +01:00
cmd f-74: api: disques additionnels xvdX sur la cible SCSI de même rang, sdX refusé, migration des clés disk/sdX #74 2026-10-23 17:19:15 +02:00
conf/agent f-85: config: dhcp.backend vaut two par défaut, dnsmasq sur déclaration explicite, mise à jour depuis la 0.1.0 documentée #85 2026-10-24 17:30:38 +02:00
docs ci: docs: liens du menu de version relatifs à switcher.json 2026-10-25 11:29:38 +01:00
internal f-81: api: default_route sans gateway réservé au mode bridge #81 2026-10-25 11:53:33 +01:00
pkg f-46: dhcpbackend: drive dnsmasq or the built-in server through one interface #46 2026-09-08 21:49:33 +02:00
release_notes 0.2.0: release 2026-10-24 20:38:41 +02:00
scripts f-64: bootstrap_kvm: paquets KVM sans les recommandés, qemu-utils explicite #64 2026-10-12 22:06:12 +02:00
systemd f-46: dhcp: add the dhcp binary, its unit and its wrapper #46 2026-09-05 23:17:59 +02:00
test/e2e 0.2.0: release 2026-10-24 20:38:41 +02:00
.gitignore f-55: lab: fichiers des nœuds sur un ISO dédié, envoi des binaires compilés en local #55 2026-10-12 15:50:54 +02:00
go.mod f-55: lab: retrait de la copie de labctl, lab.rst réduit à ce qui est propre à two #55 2026-10-12 21:21:48 +02:00
go.sum f-46: dhcpd: build dhcp replies over insomniacslk/dhcp #46 2026-09-05 23:17:58 +02:00
LICENSE update license 2026-04-21 23:19:36 +02:00
README.md 0.2.0: release 2026-10-24 20:38:41 +02:00

syonad/two

Orchestrateur réseau et machines virtuelles mono-nœud, pensé pour être piloté par un logiciel plutôt que par un humain.

Il expose une API HTTP qui crée des VPC — isolés par network namespace —, des subnets — en VXLAN ou attachés à un bridge existant — et des VM QEMU/KVM raccordées à ces subnets, avec DHCP, routage et metadata cloud-init fournis automatiquement.

Installation

curl -O https://git.g3e.fr/syonad/two/raw/branch/main/scripts/deploy.sh
bash ./deploy.sh -t 0.2.0 -i

deploy.sh se met à jour lui-même depuis la branche, télécharge binaires, units systemd et scripts depuis la release, et les vérifie contre le manifeste SHA256SUMS. Le drapeau -i prépare l'host : paquets, module br_netfilter, sysctl, et bridges.

Options utiles :

Option Effet
-t <tag> déployer une release donnée ; sans -t, la dernière publiée, préversions comprises
-b <branche>/ branche d'où viennent l'auto-mise à jour du script et le bootstrap (main/ par défaut, / final obligatoire) ; les binaires viennent toujours d'une release
-i préparer l'host (paquets, noyau, réseau)
-u <iface> interface physique d'uplink, eno1 par défaut
-B <bridge> bridge principal auquel l'uplink est rattaché
-d dry-run : affiche les commandes sans les exécuter
--noverify désactiver la vérification des sommes de contrôle

Un déploiement relève les instances dnsmasq@, dhcp@ et metadata@ actives avant l'arrêt des services, et les redémarre ensuite — c'est la seule façon de savoir lesquelles relancer.

Configuration

Un seul fichier, /etc/two/agent.yml, partagé par les quatre binaires. Voir conf/agent/config.exemple.yml pour l'ensemble des options : chemins de la base et des sockets QEMU, pool de workers, correspondance des types d'interface vers les bridges physiques, watchdog, API d'administration, journalisation.

Prise en main

# Un VPC, avec son CIDR interne
curl -X POST http://127.0.0.1:8080/vpcs \
  -d '{"name": "vp-admin", "cidr": "192.168.0.0/16"}'

# Un subnet en VXLAN dans ce VPC
curl -X POST http://127.0.0.1:8080/subnets \
  -d '{"name": "sn-000001", "vpc": "vp-admin", "mode": "vxlan", "vxlan_id": 65537,
       "iface_type": "vms", "cidr": "10.1.0.0/23"}'

# Une VM, avec une clé SSH et un user-data cloud-init en base64
curl -X POST http://127.0.0.1:8080/vms \
  -d '{"name": "i-web", "memory": 2048, "cpus": 2,
       "metadata": {"sshkey": "ssh-ed25519 AAAA…",
                    "user_data": "'"$(base64 -w0 < user-data.yml)"'"},
       "interfaces": [{"subnet": "sn-000001", "ip": "10.1.1.2", "mac": "52:54:00:01:01:02", "primary": true}],
       "storage": [{"path": "/var/lib/two/volumes/i-web.qcow2", "dev": "vda"}]}'

Les créations sont asynchrones : l'API répond 202 et l'état de la ressource passe de creating à running en base. GET /vms/i-web renvoie l'état courant.

Une VM peut porter plusieurs interfaces, dans un même VPC ; exactement une doit être marquée primary — elle porte la route par défaut et le serveur de metadata.

La spécification complète est dans api/agent.yaml.

Composants

Binaire Rôle
agent processus principal : API, dispatcher, exécution, watchdog
metadata serveur de metadata cloud-init, une instance par VM dans le netns du VPC
dhcp serveur DHCP intégré, une instance par subnet dans le netns du VPC, avec dhcp.backend: two
db inspection de la base clé-valeur en ligne de commande ; ni publié ni déployé, à compiler (go build ./cmd/db)

L'agent prend -config, les trois autres -conf.

Versions

Les notes de version sont dans release_notes/. Chaque version porte un nom de code, dérivé du rang de sa publication : anges et démons alternés, listés dans release_notes/codenames.md.