Documentation : README et référence de l'API PVE 9.x utilisée
This commit is contained in:
claude Bot committed
1 parent
e5f3583086
commit
0b53bad1c1
2 files changed
+217
No files matched your search
@@ -0,0 +1,132 @@
|
||||
# pve-confsync
|
||||
|
||||
Synchronisation d'une partie de la configuration d'un cluster Proxmox VE 9.x
|
||||
« référence » vers N clusters « clients », via l'API PVE et des tokens API.
|
||||
Sens unique référence → clients. Pas de VM, pas de disques.
|
||||
|
||||
**État : phase 0 (CLI).** Export, diff et apply en YAML pour les options datacenter
|
||||
et le SDN (zones VLAN/VXLAN, VNets, subnets). Testé contre un faux serveur PVE ;
|
||||
**pas encore testé sur les clusters de labo.**
|
||||
|
||||
## Périmètre
|
||||
|
||||
| Type (`kind`) | API | Politique par défaut |
|
||||
|---|---|---|
|
||||
| `datacenter-options` | `/cluster/options` | `tag-style`, `registered-tags`, `user-tag-access`, `next-id` en `sync`, le reste ignoré ; `webauthn`, `u2f`, `http_proxy` jamais synchronisés |
|
||||
| `sdn-zone` (vlan, vxlan) | `/cluster/sdn/zones` | `nodes`, `bridge`, `peers`, `fabric`, `dns`, `reversedns`, `dnszone` en `override` (mapping client) ; le reste en `sync` |
|
||||
| `sdn-vnet` | `/cluster/sdn/vnets` | `sync` |
|
||||
| `sdn-subnet` | `/cluster/sdn/vnets/{vnet}/subnets` | `sync` |
|
||||
|
||||
Hors périmètre v1 : EVPN (et les zones simple, QinQ, faucet, avec leurs VNets, ignorées
|
||||
avec un avertissement), firewall, storage, pools/ACL, jobs, secrets.
|
||||
|
||||
Détail des routes, schémas et droits, avec les sources : [docs/api-pve.md](docs/api-pve.md).
|
||||
|
||||
## Fonctionnement
|
||||
|
||||
```
|
||||
lecture source -> normalisation -> diff -> plan -> apply -> vérification
|
||||
```
|
||||
|
||||
- **Lecture** : la référence est lue en configuration SDN *appliquée* (`running=1`) ; les
|
||||
clients 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 de la référence), `ignore`, `override` (valeur fournie
|
||||
uniquement par le `mapping` du client). Le mapping d'un client est prioritaire sur la
|
||||
référence. Résolution : politique du client → 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 le client a déjà des changements SDN
|
||||
en attente : on ne mélange pas nos modifications avec celles de quelqu'un d'autre.
|
||||
- **Vérification** : relecture du client, nouveau plan qui doit être vide, et aucune zone en
|
||||
`error` sur les nœuds (`/nodes/{node}/sdn/zones`).
|
||||
|
||||
## Utilisation
|
||||
|
||||
```sh
|
||||
go build -o pve-confsync ./cmd/pve-confsync
|
||||
cp examples/confsync.example.yaml confsync.yaml # puis adapter
|
||||
|
||||
./pve-confsync check # accès, version 9.x, droits des tokens
|
||||
./pve-confsync export -o ref.yaml # état normalisé de la référence (versionnable dans Git)
|
||||
./pve-confsync diff # écarts par client ; code retour 2 s'il y en a
|
||||
./pve-confsync diff -format json
|
||||
./pve-confsync apply # dry-run (défaut) : affiche le plan, n'écrit rien
|
||||
./pve-confsync apply -client site-a -confirm # applique ; SDN : saisir le nom du client
|
||||
./pve-confsync apply -source ref.yaml -confirm -yes # depuis un export Git, sans question
|
||||
```
|
||||
|
||||
Avec docker compose (images et utilisateur non privilégié alignés sur Logstream) :
|
||||
|
||||
```sh
|
||||
mkdir -p secrets && printf '%s' 'xxxxxxxx-...' > secrets/pve_ref
|
||||
chmod 600 secrets/* && sudo chown 10001 secrets/* # lisibles par l'utilisateur du conteneur uniquement
|
||||
docker compose run --rm confsync check
|
||||
docker compose run --rm confsync apply -confirm
|
||||
```
|
||||
|
||||
## Sécurité
|
||||
|
||||
- Secrets des tokens : jamais dans le YAML (`token_secret` en clair est refusé) ; lus depuis
|
||||
une variable d'environnement (`token_secret_env`) ou un fichier (`token_secret_file`,
|
||||
secret docker). Ils ne sont ni affichés ni journalisés. Le chiffrement au repos arrive avec
|
||||
le stockage SQLite (phase 1).
|
||||
- TLS : `fingerprint` (pinning SHA-256 du certificat, adapté aux certificats auto-signés PVE),
|
||||
`ca_file`, ou `insecure: true` réservé au labo.
|
||||
- Tokens (privilege separation activée, l'ACL doit être posée sur l'utilisateur et le token) :
|
||||
|
||||
```sh
|
||||
# référence : lecture seule
|
||||
pveum role add ConfSyncRO --privs "Sys.Audit SDN.Audit"
|
||||
pveum user add confsync@pve
|
||||
pveum user token add confsync@pve ro --privsep 1
|
||||
pveum acl modify / --users confsync@pve --roles ConfSyncRO
|
||||
pveum acl modify / --tokens 'confsync@pve!ro' --roles ConfSyncRO
|
||||
|
||||
# clients : Sys.Modify uniquement si les options datacenter sont synchronisées
|
||||
pveum role add ConfSyncRW --privs "Sys.Audit Sys.Modify SDN.Audit SDN.Allocate"
|
||||
```
|
||||
|
||||
`check` signale un token de référence capable d'écrire et un token client à qui il manque
|
||||
un droit.
|
||||
|
||||
## Arborescence
|
||||
|
||||
```
|
||||
cmd/pve-confsync/ CLI (check, export, diff, apply)
|
||||
internal/pve/ client API : token, TLS, form-encoding, version, tâches
|
||||
internal/pve/pvetest/ faux serveur PVE 9.x pour les tests
|
||||
internal/model/ objets génériques, snapshot YAML, valeurs canoniques
|
||||
internal/adapter/ un adaptateur par type : routes, champs calculés, locaux, immuables
|
||||
internal/config/ configuration YAML : clusters, politiques, mappings, sélection
|
||||
internal/engine/ lecture, plan, apply (verrou SDN, rollback), vérification
|
||||
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 : synchro complète, mapping
|
||||
manquant, rollback sur erreur, refus de PVE 8, prune et ordre de suppression, forme
|
||||
canonique des options datacenter, CLI dry-run/apply/export).
|
||||
|
||||
## Phasage
|
||||
|
||||
0. **CLI** export / diff / apply YAML (options datacenter, tags, SDN). ← ici
|
||||
1. UI lecture seule : clusters, diff visuel par client. 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 / Synchroniser (par objet, par client, global), journal des exécutions.
|
||||
3. Planification, détection de dérive en lecture seule, notifications.
|
||||
|
||||
## Reste à faire avant la phase 1
|
||||
|
||||
- Valider sur les deux clusters de labo : 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).
|
||||
Reference in new issue
Block a user