Ce dépôt contient les playbooks, rôles, inventaires et templates Ansible servant à construire, configurer, maintenir et documenter les serveurs d’un écosystème numérique souverain.
`Set-OPS` est le moteur global d’exploitation d’écosystèmes numériques souverains.
Le template Debian 13 Proxmox est seulement un sous-ensemble du dépôt. Le dépôt ne doit jamais être restructuré autour d’un seul besoin ponctuel.
---
## Mission et identité
Au-delà de l’exploitation, `Set-OPS`**définit et construit un écosystème numérique souverain** : une infrastructure interne auto-suffisante, sans dépendance SaaS, dont tous les piliers sont décrits en code et reliés entre eux.
- confiance — autorité de certification interne (ACME) ;
- nommage et adressage — DNS interne et nomenclature dérivable ;
- données — bases relationnelles et cache, avec registre des connexions ;
- communication — relais courriel interne ;
- observabilité et supervision — métriques, journaux, tableaux de bord, supervision active ;
- applicatif — services internes (forge, etc.) et couche web.
Propriétés visées, avec leurs nuances honnêtes :
- **Souverain / auto-suffisant** : c’est l’objectif. Aucune dépendance à un service externe pour la confiance, l’identité, le nom ou la communication. Cela justifie le choix de construire plutôt qu’assembler des SaaS.
- **Déclaratif et convergent** : l’état voulu est décrit dans des registres machine-lisibles (`instance/plan/nomenclature.yml`, `docs/dependances-groupes.yml`, `instance/plan/bases-donnees.yml`) et appliqué par les groupes Ansible. Ces registres sont la **source unique de vérité**.
- **Pas (encore) auto-réparé** : la convergence est pilotée par l’opérateur (GUI / CLI / `make`), pas une boucle fermée d’auto-remédiation.
- **Définition avant déploiement** : une grande partie est planifiée et validée (`--syntax-check`, `ansible-lint`) mais pas encore exécutée contre des VM réelles. Ne jamais présenter un rôle non déployé comme « en production ».
Conséquence pour le travail : préserver la discipline qui tient l’ensemble — registres comme source unique, dépendances explicites, validation de chaque pièce, secrets hors dépôt. C’est ce qui empêche l’écosystème de devenir un objet ingérable. Le template Debian 13 reste la fondation (le moule des VM), pas la finalité.
---
## Le plan et la génération de l’inventaire (méta-classe)
`Set-OPS` se pilote par un **plan**, pas par l’édition directe de l’inventaire.
L’inventaire Ansible est **généré** depuis le plan.
**RÈGLE D’OR : `instance/inventories/production/hosts.yml` est un artefact GÉNÉRÉ. Ne jamais l’éditer à la main.** On édite le *plan*, puis on régénère.
- L’**application** est l’entité pivot ; le **groupe** Ansible n’est qu’une capacité (le rôle appliqué), plus une cible de liaison.
- Le plan vit dans des registres machine-lisibles : `instance/plan/serveurs.yml` (les VM), `instance/plan/applications.yml` (les services et leurs liens `requiert`/`utilise`/`expose`), `instance/plan/bases-donnees.yml`, `instance/plan/domaines.yml`, `instance/plan/nomenclature.yml`.
- Génération : `make instancier` (génère + diff sémantique), `make instancier-appliquer` (régénère `hosts.yml`, refuse si le diff n’est pas vide — `FORCE=1` pour un changement intentionnel).
- Flux : **éditer le plan → `make instancier` (revoir le diff) → `make instancier-appliquer` → déployer**. Via le GUI : vues **Serveurs** et **Applications**, puis « Appliquer le plan » (la vue Inventaire est en lecture seule).
- VMID / IP / VLAN / passerelle sont **dérivés** de la `fonction` via la nomenclature ; les groupes d’une VM sont dérivés (socle + services des applications + intégrations + état).
- Garde-fous : validateurs de registres, diff-vide, `node --check` du JS du GUI (`scripts/verifier_gui.py`, dans `make inventaire-verifier`), git comme filet.
**Plan de contrôle gelé en périmètre** : le GUI, le générateur, l'IPAM et la modélisation sont volontairement *maison* et **souverains**, mais leur périmètre est gelé. Ne pas y ajouter de fonctionnalités de type NetBox/AWX (RBAC, historique d'audit, détection de conflits IPAM, API riche) : le besoin réel d'une de ces fonctions est le **signal d'adopter l'outil mûr correspondant** (NetBox pour la source de vérité, AWX pour l'exécution), pas de le réimplémenter. Décision et seuils : **`docs/positionnement.md`**.
---
## Règle d’or IA
Un seul agent IA travaille dans ce dépôt à la fois.
- Soit Codex.
- Soit Claude Code.
- Jamais les deux simultanément.
Tout changement significatif doit être consigné dans `CHANGELOG.md`.
---
## Principes
1. Toujours lire l’existant avant de modifier.
2. Ne jamais introduire de secret en clair.
3. Ne jamais casser l’idempotence Ansible.
4. Ne jamais exécuter d’action destructive sans confirmation explicite.
5. Préférer la simplicité à l’ingénierie excessive.
6. Documenter ce qui est utile à l’exploitation réelle.
7. Préférer les correctifs ciblés aux régénérations massives.
8. Ne jamais supposer qu’un rôle est complet sans l’avoir inspecté.
9. Ne jamais déclarer un playbook prêt si la validation minimale échoue.
10.**Impératif : Set-OPS doit rester pleinement exploitable par un humain SANS IA.** La doc, `make` et le GUI sont l’interface primaire et complète. Ne jamais introduire de fonctionnalité qui *exige* une IA pour s’en servir. L’IA n’assiste que le mainteneur pour faire évoluer l’outil — jamais l’utilisateur final. (Le bon étalon : un sysadmin humain réussit depuis la doc. `AGENTS.md`/`CLAUDE.md` ne font pas partie de l’outil livré.)
---
## Sécurité
Ne jamais commiter :
- mots de passe ;
- clés privées SSH ;
- tokens API ;
- secrets non chiffrés ;
- fichiers `.env` sensibles ;
- certificats privés ;
- backups réels ;
- exports de production non anonymisés.
Les secrets doivent être gérés hors dépôt ou avec un mécanisme explicitement prévu, par exemple :
- Ansible Vault ;
- fichier local non versionné ;
- secret injecté hors dépôt ;
- gestionnaire de secrets approuvé.
---
## Actions destructives
Toute action destructive doit exiger une variable explicite, par exemple :
```yaml
confirm_destructive_action: true
```
Sont considérées comme destructives ou risquées :
- modification bloquante de SSH ;
- activation ou modification d’un pare-feu ;
- suppression d’utilisateurs ;
- suppression de paquets critiques ;
- formatage disque ;
- modification de partitions ;
- redémarrage massif ;
- purge de données ;
- changement réseau pouvant couper l’accès ;
- modification d’un hyperviseur Proxmox ;
- opération sur stockage, iSCSI, ZFS ou Ceph.
Sans confirmation explicite, refuser l’exécution.
---
## Règle de modification du dépôt
Avant toute modification, exécuter ou demander l’équivalent de :
```bash
git status --short
find . -maxdepth 3 -type f | sort
```
Ne pas remplacer massivement l’arborescence sans demande explicite.
Avant de modifier un fichier, lire son contenu actuel.
Après modification, indiquer clairement :
- les fichiers créés ;
- les fichiers modifiés ;
- les commandes de validation exécutées ;
- les tests non exécutés ;
- les limites connues.
---
## Validation Ansible obligatoire
Avant de proposer un changement comme terminé, vérifier au minimum la syntaxe du playbook touché.
Éviter `shell` et `command` sauf nécessité réelle.
Lorsqu’une commande shell est nécessaire, elle doit être encadrée avec les paramètres appropriés selon le cas :
-`changed_when`
-`failed_when`
-`creates`
-`removes`
---
## Structure générale du dépôt
Le dépôt peut contenir progressivement :
```text
inventories/
playbooks/
roles/
templates/
files/
scripts/
docs/
```
Les playbooks peuvent être classés par domaine :
```text
playbooks/
├── groupes/
├── maintenance/
├── monitoring/
├── networking/
├── proxmox/
├── modeles_vm/
├── web/
├── database/
├── identity/
├── backup/
└── applications/
```
Les rôles peuvent être ajoutés progressivement selon les besoins.
Ne pas créer de structure inutile uniquement pour donner une impression de complétude.
La conformité normale des VM déployées doit passer par `playbooks/groupes/`.
Ne pas maintenir en parallèle des playbooks de couches génériques comme `playbooks/socle/` ou `playbooks/durcissement/` lorsqu'un groupe opérationnel exprime déjà cet état voulu.
---
## Interface opérateur Makefile
Le `Makefile` est l'interface opérateur privilégiée pour les gestes courants.
Les commandes `make` doivent simplifier l'exploitation Ansible sans masquer les playbooks réellement exécutés.
Préférer quelques cibles claires et utiles :
- validation du dépôt ;
- inspection des inventaires ;
- ajout ou mise à jour d'un hôte dans un inventaire ;
- association d'un hôte à ses groupes ;
- déploiement ou remise en conformité d'un hôte ;
- déploiement ou remise en conformité d'un groupe ;
- préparation, vérification et nettoyage protégé d'un modèle de VM.
Ne pas multiplier les cibles `make` secondaires si elles ne correspondent pas à un geste réel d'exploitation.
Les cibles d'exploitation des VM doivent privilégier les groupes :
```text
make deployer HOTE=web-01
make deployer-groupe GROUPE=serveur_debian
make hote-planifier HOTE=obs-01 VMID=94101 GROUPES="serveur_debian serveur_durci serveur_prometheus"
```
Éviter les cibles parallèles qui réappliquent les mêmes rôles par couche, par exemple `make socle`, `make durcissement`, `make converger` ou `make deployer-vm`.
Toute cible `make` qui lance une action destructive ou risquée doit exiger une confirmation explicite.
---
## Convention groupes et playbooks
Chaque groupe opérationnel Ansible doit avoir un playbook homonyme dans `playbooks/groupes/`.
La convention attendue est :
```text
groupe Ansible : serveur_debian
playbook : playbooks/groupes/serveur_debian.yml
```
L'appartenance aux groupes détermine les services, intégrations et politiques appliqués à une VM.
`playbooks/groupes/` est la source officielle de conformité pour les VM déployées.
Un playbook de groupe doit cibler son groupe homonyme, pas `all`, sauf justification explicite.
Les concepts comme socle Debian ou durcissement commun doivent être représentés par des groupes explicites :
```text
serveur_debian -> socle commun Debian
serveur_durci -> durcissement commun
client_pki -> intégration cliente PKI / ACME
```
Ne pas dupliquer ces mêmes rôles dans des playbooks de couches séparés.
Quand un nouveau groupe opérationnel est ajouté :
- créer le playbook homonyme dans `playbooks/groupes/` ;
- documenter son intention opérationnelle ;
- déclarer ses dépendances causales dans `docs/dependances-groupes.yml` si son exécution requiert un autre service actif ;
- prévoir les rôles nécessaires ;
- valider au minimum sa syntaxe ;
- l'ajouter aux facilités d'exploitation si l'opérateur doit l'utiliser directement.
---
## Cycle de vie et conformité des VM
Set-OPS doit gérer le cycle de vie complet des VM de l’instance :
```text
VM Debian minimale
→ goldenisation du template
→ clonage
→ identité initiale cloud-init
→ conformité par groupes Ansible
→ intégrations transversales
→ conformité continue
```
Le template est seulement la fondation. Les VM existantes et futures doivent converger vers l'état voulu par les playbooks de groupes.
Les rôles et playbooks doivent donc être conçus pour être relancés régulièrement, sans effet secondaire inutile.
Le groupe d'inventaire attendu pour les VM Debian gérées est :
```text
serveur_debian
```
Les groupes spécialisés doivent s'ajouter selon les besoins réels, par exemple :
