pve-confsync/README.md

pve-confsync

Réplication d'une partie de la configuration d'un cluster Proxmox VE 9.x primaire vers une ou plusieurs cibles. Sens unique primaire → cibles. Pas de VM, pas de disques. Tout se fait depuis l'interface web : plus de CLI ni de fichier YAML.

État : phases 0 à 2, version « full web ». Ajout des clusters (un par un ou en lot), choix du primaire, éléments répliqués et cibles choisis dans des menus, écarts par cible, dry-run et réplication par objet, par cible ou global, journal, audit. Testé contre un faux serveur PVE (API + SSH) ; pas encore testé sur un vrai cluster.

Périmètre

Type (kind)	Accès	Politique par défaut
datacenter-options	API /cluster/options	tag-style, registered-tags, user-tag-access, next-id en sync, le reste ignoré ; webauthn, u2f, http_proxy jamais répliqués
pve-group	API /access/groups	sync
pve-role	API /access/roles	sync (rôles intégrés ignorés)
pve-user	API /access/users	sync, comptes du royaume pve uniquement
pve-password	SSH /etc/pve/priv/shadow.cfg	sync (haché recopié tel quel, jamais affiché)
sdn-zone (vlan, vxlan)	API /cluster/sdn/zones	nodes, bridge, peers, fabric, dns, reversedns, dnszone en override (mapping de la cible) ; le reste en sync
sdn-vnet	API /cluster/sdn/vnets	sync
sdn-subnet	API /cluster/sdn/vnets/{vnet}/subnets	sync

Les comptes du realm pve et leurs mots de passe forment un seul élément à répliquer ; ils exigent leurs groupes, que le menu « Éléments répliqués » coche avec eux. Un parent absent de la cible et non répliqué est une erreur bloquante.

Hors périmètre : EVPN (et les zones simple, QinQ, faucet, avec leurs VNets, ignorées avec un avertissement), firewall, storage, pools, ACL, jobs, comptes @pam et autres royaumes.

Détail des routes, schémas et accès, avec les sources : docs/api-pve.md.

Réplication de nœuds

Deuxième mode, séparé du premier dans l'interface (sélecteur « Clusters (API) | Nœuds (fichiers) » en haut de page) : un profil réplique la configuration système d'un nœud maître vers des nœuds cibles, du même cluster ou d'un autre.

Élément	Accès	Rechargement	Particularités
network	API /nodes/{node}/network (écrit interfaces.new)	PUT /nodes/{node}/network (ifreload -a)	cidr, cidr6, gateway, gateway6 en override : chaque nœud garde ses adresses ; mapping des noms d'interfaces par cible (eno1=enp65s0f0, VLAN suivis) ; interface physique absente = bloquant ; options que l'API n'écrit pas (bond-miimon, post-up…) signalées, non répliquées
dns	API /nodes/{node}/dns	aucun	domaine de recherche obligatoire pour l'API
multipath	SSH /etc/multipath.conf	multipathd reconfigure
wwids	SSH /etc/multipath/wwids	multipathd reconfigure	ajout seul des WWID du maître
chrony	SSH /etc/chrony/chrony.conf, sources.d/*.sources	systemctl restart chrony
sysctl	SSH /etc/sysctl.d/*.conf	sysctl --system
interfaces-d	SSH /etc/network/interfaces.d/*	ifreload -a	interfaces.d/sdn (généré par le SDN) jamais touché

Jamais répliqués : /etc/pve, corosync, hostname, machine-id, clés SSH, IQN iSCSI, /etc/frr.

• Accès : « Découvrir les nœuds » lit /cluster/status de chaque cluster (adresse de chaque nœud). SSH en root sur chaque nœud, avec le mot de passe de son cluster ou le sien ; clé d'hôte épinglée au premier test, qui vérifie aussi que le nœud répond bien sous son nom.
• Règles : politiques par champ (réseau, DNS), lignes protégées par expression régulière pour les fichiers (gardées de la cible), valeurs propres à une cible (vmbr1 cidr=…).
• Apply (administrateurs), un nœud après l'autre, arrêt au premier échec : un script SSH vérifie que chaque fichier est celui du dry-run (SHA-256), sauvegarde dans /var/lib/pve-confsync/backup/<date>/ avec un restore.sh, écrit de façon atomique (fichier temporaire puis mv, droits et propriétaire gardés) ; l'API écrit les interfaces et le DNS ; les rechargements suivent. Un rechargement en échec restaure les sauvegardes.
• Filet réseau : avant de recharger le réseau, un timer systemd est armé sur le nœud (pve-confsync-restore-<date>) : sans nouvelle connexion SSH et API dans les 120 s, le nœud relance restore.sh et ifreload -a de lui-même. Confirmation tapée (nom du nœud, ou du profil en global) dès qu'un plan recharge le réseau. Refus si la cible a déjà des changements réseau en attente (interfaces.new).

Fonctionnement

lecture source -> normalisation -> diff -> plan -> apply -> vérification

• Lecture : le primaire est lu en configuration SDN appliquée (running=1) ; les cibles en configuration courante. Chaque cluster est refusé si un nœud en ligne n'est pas en PVE 9.x (/nodes/{node}/version).
• Normalisation : objets JSON génériques → champs canoniques (chaînes, listes triées, property strings à clés triées). Les champs calculés par PVE sont retirés.
• Politiques : sync (copie du primaire), ignore, override (valeur fournie uniquement par le mapping de la cible). Le mapping d'une cible est prioritaire sur le primaire. Résolution : politique de la cible → politique globale → défaut de l'adaptateur.
• Plan : création / mise à jour (champs modifiés, champs à supprimer) ; suppression d'objets uniquement avec prune (option explicite), dépendants d'abord. Erreurs bloquantes : champ obligatoire absent à la création (ex. bridge d'une zone VLAN sans mapping), champ immuable modifié (type de zone, vnet d'un subnet).
• Apply SDN : POST /cluster/sdn/lock → écritures avec lock-token → PUT /cluster/sdn (commit + rechargement réseau, suivi de la tâche). Toute erreur avant le commit déclenche POST /cluster/sdn/rollback. Le verrou est refusé si la cible a déjà des changements SDN en attente : on ne mélange pas nos modifications avec celles de quelqu'un d'autre.
• Apply comptes : API pour groupes, rôles et comptes ; mots de passe par SSH (script perl sous lock_shadow_config, comme pveum passwd).
• Vérification : relecture de la cible, nouveau plan qui doit être vide, et aucune zone en error sur les nœuds (/nodes/{node}/sdn/zones).

Démarrage

go run ./cmd/pve-confsync -demo        # démo : faux clusters PVE, http://localhost:8080
docker compose -f docker-compose.demo.yml up -d --build   # même démo en conteneur
docker compose up -d                   # production : données dans le volume /data

La clé AES-256 des mots de passe en base est créée au premier démarrage dans /data/secret.key (à sauvegarder : sans elle, les mots de passe enregistrés sont perdus). En production, on peut la garder hors du volume en secret docker (CONFSYNC_SECRET_KEY_FILE, voir les commentaires de docker-compose.yml). Port publié : CONFSYNC_PORT (.env, 8080 par défaut).

Le mode démo démarre un primaire PVE 9.1, deux cibles avec des écarts (dont un mapping manquant, bloquant) et un cluster PVE 8 refusé. Comptes admin, operateur et lecteur, mot de passe confsync-demo.

Base vide : la page de connexion propose de créer le premier administrateur (12 caractères minimum). Tant que ce n'est pas fait, le premier qui atteint l'instance devient administrateur : ne pas l'exposer avant. Alternative : CONFSYNC_ADMIN_USER et CONFSYNC_ADMIN_PASSWORD / _FILE créent ce compte au démarrage.

Interface web

• Clusters : ajout d'un cluster (URL https://…:8006, mot de passe root) ou d'une liste (« nom URL » par ligne, même mot de passe), test (API, version 9.x, SSH), rôle primaire / cible / désactivé. Un seul primaire, jamais écrit.
• Éléments répliqués et Cibles : menus de la vue Écarts ; les cibles décochées sont exclues du global (choix mémorisé dans le navigateur).
• Écarts : une carte par cluster (version, compteurs à créer / modifier / erreurs / hors primaire), puis les objets de la cible choisie ; le détail d'un objet montre pour chaque champ la politique, la valeur du primaire, le mapping, la valeur actuelle et la valeur après réplication. Les hachés sont masqués (<masqué xxxxxx>).
• Dry-run / Répliquer par objet (avec ses parents à créer), par cible ou global. Dans le dry-run, chaque élément peut être exclu de l'exécution (« Ne pas répliquer ») ; le dry-run est alors relancé sans lui, sauf ce dont les autres ont besoin. La réplication passe toujours par un dry-run : le serveur recalcule le plan et refuse s'il a changé depuis (empreinte du plan). Avec des changements SDN, il faut taper le nom de la cible (celui du primaire en global). Une seule réplication à la fois.
• Journal des dry-runs et réplications et Audit (connexions, actions, modifications ; admin).
• Paramètres : sélection, politiques, mapping par cible, suppression (désactivée par défaut), utilisateurs locaux, compte, apparence.

Rôles : admin (tout), operator (dry-run et réplication), viewer (lecture). Les comptes locaux restent disponibles même avec OIDC. Toutes les variables sont reprises, commentées, dans .env.example (cp .env.example .env).

Variable	Défaut	Rôle
LISTEN	:8080	adresse d'écoute
DATA_DIR	/data	base SQLite, secret.key, session.key
CONFSYNC_SECRET_KEY / _FILE	DATA_DIR/secret.key (créée)	clé AES-256 (hex ou base64) des mots de passe en base
CONFSYNC_ADMIN_USER, CONFSYNC_ADMIN_PASSWORD / _FILE	admin, vide	premier administrateur sans passer par la page web
AUTH_LOCAL	true	comptes locaux
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET / _FILE, OIDC_REDIRECT_URL		OIDC (code + PKCE) ; OIDC_REDIRECT_URL complète, par ex. https://confsync.example.org/auth/callback
OIDC_SCOPES, OIDC_GROUPS_CLAIM	openid profile email, groups	ajouter le scope qui fournit les groupes chez l'IdP
OIDC_ADMIN_GROUP, OIDC_OPERATOR_GROUP, OIDC_DEFAULT_ROLE	viewer	rôle d'après les groupes
SESSION_TTL	12h	durée des sessions
CONFSYNC_DEMO	false	mode démo

Sécurité

• Accès PVE en root@pam (API par ticket, SSH avec le même mot de passe) : nécessaire pour les mots de passe du royaume pve, absents de l'API. Le compte root ne doit pas avoir de TFA (refusé). Le primaire n'est jamais écrit.
• Épinglage au premier test : empreinte SHA-256 du certificat TLS (mode par défaut, adapté aux certificats auto-signés PVE) et clé d'hôte SSH. Une clé SSH différente ensuite bloque l'accès ; l'accepter demande une action explicite (« faire confiance à la nouvelle clé »). Changer l'URL ou le nœud SSH oublie les empreintes. Autres modes TLS : CA (PEM), CA système, insecure (labo).
• Mots de passe root chiffrés en base (AES-256-GCM, clé hors base), jamais renvoyés au navigateur ni journalisés. Les hachés du shadow sont masqués dans l'UI, le journal et les réponses JSON.
• Interface : mots de passe PBKDF2-SHA256 (600 000 itérations), cookie de session signé (HttpOnly, SameSite=Lax, Secure derrière HTTPS) invalidé au changement de mot de passe, en-tête X-Confsync exigé sur les écritures (CSRF), CSP sans script ni style en ligne.

Arborescence

cmd/pve-confsync/      serveur web (seul point d'entrée)
internal/service/      analyse pour l'UI : lecture parallèle, plans, lignes de diff par champ
internal/store/        SQLite : clusters (mots de passe chiffrés, rôles, empreintes), utilisateurs, journal, audit
internal/server/       HTTP : auth locale + OIDC, rôles, API, jobs de synchronisation
internal/demo/         faux clusters du mode démo
web/                   UI embarquée (index.html, app.js, style.css, login.html)
internal/pve/          client API : ticket root@pam, TLS épinglé, form-encoding, version, tâches
internal/sshx/         SSH root, clé d'hôte épinglée
internal/pve/pvetest/  faux serveur PVE 9.x (API + SSH) pour les tests
internal/model/        objets génériques, valeurs canoniques
internal/adapter/      un adaptateur par type : routes, champs calculés, locaux, immuables
internal/config/       configuration en mémoire : clusters, politiques, mappings, sélection
internal/engine/       lecture, plan, apply (verrou SDN, rollback), vérification
internal/nodesync/     réplication de nœuds : réseau et DNS (API), fichiers (SSH), diff, sauvegarde, restauration
docs/api-pve.md        routes et schémas vérifiés dans les sources PVE

Tests : go test ./... (bout en bout contre le faux serveur : réplication SDN et comptes avec mots de passe par SSH, mapping manquant, parent absent, rollback sur erreur, refus de PVE 8, prune et ordre de suppression ; sélection et dépendances ; chiffrement, migration de schéma, premier administrateur ; serveur depuis une base vide : création de l'admin, ajout des clusters, épinglage, primaire, réplication globale, primaire jamais écrit).

Phasage

0. Moteur export / diff / apply (options datacenter, tags, SDN) ; la CLI a été retirée.
1. UI lecture seule : clusters, diff visuel par cible. Ergonomie reprise de Logstream (web/index.html, style.css, app.js, login.html, auth locale + OIDC, audit) ; SQLite (clusters, profils, mappings, historique, audit), secrets chiffrés.
2. UI d'action : Dry-run / Répliquer (par objet, par cible, global), journal ; gestion des clusters en web, primaire / cibles, comptes et mots de passe du royaume pve. ← ici
3. Planification, détection de dérive en lecture seule, notifications.

Reste à faire

• Valider sur un vrai cluster : écriture du shadow par SSH, forme de /access/users?full=1, forme réelle des réponses (nodes, dhcp-range, booléens), comportement de PUT /cluster/options avec delete.
• Exploiter GET /cluster/sdn/dry-run (diff frr / interfaces, PVE ≥ 9.2 environ) pour enrichir le dry-run SDN.
• Rechargement en échec après commit : aujourd'hui signalé, pas d'annulation automatique (la configuration appliquée est déjà la nouvelle).