Set-OPS/AGENTS.md

# AGENTS.md — Set-OPS

## Rôle du dépôt

Ce dépôt contient les playbooks, rôles, inventaires et templates Ansible servant à construire, configurer, maintenir et documenter les serveurs de Chezlepro Inc.

`Set-OPS` est le dépôt global d’exploitation de Chezlepro Inc.

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 l’écosystème numérique souverain de Chezlepro Inc.** : une infrastructure interne auto-suffisante, sans dépendance SaaS, dont tous les piliers sont décrits en code et reliés entre eux.

Piliers de l’écosystème :

- identité — machines (PKI / certificats) et utilisateurs (annuaire + SSO) ;
- 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.

Référence complète : **`docs/plan-et-generation.md`**.

**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, Ceph ou TrueNAS.

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é.

Exemple pour le template Debian 13 Proxmox :

```bash
ansible-playbook -i instance/inventories/lab/hosts.yml playbooks/modeles_vm/debian13_proxmox_preparer.yml --syntax-check
```

Pour un autre playbook, remplacer le chemin par le playbook concerné.

Ne jamais déclarer un playbook prêt si `--syntax-check` échoue.

Si `ansible-lint` est disponible, l’utiliser :

```bash
ansible-lint
```

Si `ansible-lint` n’est pas disponible, le signaler clairement. Ne pas inventer un résultat.

---

## Règle pour les handlers Ansible

Chaque rôle qui utilise `notify` doit contenir son handler dans le rôle lui-même.

Exemple :

```text
roles/ssh_baseline/tasks/main.yml
roles/ssh_baseline/handlers/main.yml
```

Ne pas dépendre d’un handler défini dans un autre rôle, sauf justification explicite.

Tout `notify` doit pointer vers un handler existant.

Commandes de vérification utiles :

```bash
find roles -path '*/tasks/*.yml' -exec grep -H "notify:" {} \;
find roles -path '*/handlers/main.yml' -print
```

Avant de livrer un rôle, vérifier que chaque handler référencé existe réellement.

---

## Style Ansible attendu

Les playbooks doivent être :

- idempotents ;
- lisibles ;
- sobres ;
- compatibles Debian 13 sauf exception documentée ;
- testables avec `--check` autant que possible ;
- sécuritaires par défaut ;
- sans dépendances SaaS ou cloud inutiles.

Préférer les modules Ansible standards :

- `ansible.builtin.apt`
- `ansible.builtin.template`
- `ansible.builtin.copy`
- `ansible.builtin.service`
- `ansible.builtin.systemd`
- `ansible.builtin.lineinfile`
- `ansible.builtin.file`
- `ansible.builtin.user`
- `ansible.builtin.group`

É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_dns      -> intégration cliente DNS
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 Chezlepro :

```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 :

```text
client_dns
client_pki
client_ldap
client_supervision
client_metrique
serveur_web_frontal
serveur_postgresql
serveur_prometheus
```

Ne pas cibler `all` par défaut pour un playbook qui ne s'applique pas réellement à tous les hôtes.

---

## Services centraux et intégrations clientes

Pour chaque service d'infrastructure, distinguer deux responsabilités :

```text
service serveur     : installe et configure le service central
intégration cliente : raccorde les VM au service central
```

Exemples :

```text
PowerDNS serveur  → clients DNS / resolver / enregistrements
step-ca serveur   → confiance CA / ACME client
LDAP serveur      → SSSD / NSS / PAM client
Keycloak serveur  → intégrations OIDC applicatives
Prometheus        → node_exporter sur les VM
Icinga2           → agent ou checks distants
Grafana           → datasources et dashboards côté plateforme
```

Quand un nouveau service central est ajouté, prévoir aussi le ou les rôles clients nécessaires pour intégrer les VM existantes et futures.

Les dépendances entre groupes doivent être déclarées dans :

```text
docs/dependances-groupes.yml
```

Ces dépendances servent à refuser un déploiement lorsque les prérequis actifs sont absents et à préparer les futurs checks de supervision.

Les intégrations clientes doivent être :

- idempotentes ;
- activables par inventaire ou variables ;
- désactivées par défaut si leur dépendance centrale n'existe pas ;
- documentées avec leurs prérequis ;
- testables avec `--syntax-check` et, lorsque possible, `--check`.

Ne pas mettre les intégrations applicatives ou les agents spécialisés dans le golden template, sauf justification opérationnelle explicite.

---

## Variables et inventaires

Les variables de rôle doivent utiliser un préfixe correspondant au rôle.

Exemples :

```yaml
ssh_durcissement_port: 22
nftables_socle_enabled: false
fail2ban_ssh_enabled: true
```

Séparer clairement :

```text
variables de template    : construction du golden template
variables de conformité  : état voulu des VM déployées
variables applicatives   : services et rôles spécialisés
```

Les variables de conformité ne doivent pas couper l'accès SSH, DNS ou réseau sans validation explicite.

Toute variable susceptible de provoquer une action destructive, bloquante ou irréversible doit exiger une confirmation explicite.

---

## Langue et nommage

La surface destinée à l'opérateur doit être en français.

À franciser :

- noms de groupes d'inventaire ;
- cibles `make` ;
- variables de commande maison ;
- libellés et messages des scripts maison ;
- noms des playbooks maison quand ils sont exposés à l'opérateur ;
- documentation d'exploitation.

À ne pas franciser automatiquement :

- mots-clés Ansible (`hosts`, `roles`, `tasks`, `handlers`, `vars`, `become`) ;
- noms de modules Ansible (`ansible.builtin.apt`, `ansible.builtin.template`, etc.) ;
- conventions techniques imposées par un outil ;
- noms de rôles existants, sauf demande explicite ou migration ciblée justifiée.

Les variables de rôle peuvent rester alignées sur le nom technique du rôle, mais elles doivent conserver un préfixe clair et stable.

Ne pas faire de renommage massif uniquement pour franciser si cela augmente le risque sans bénéfice opérationnel immédiat.

---

## Template Debian 13 Proxmox

Le template Debian 13 Proxmox doit rester un socle commun.

Il peut contenir :

- Debian minimal ;
- SSH ;
- sudo ;
- compte technique `ansible` ;
- sudo NOPASSWD pour `ansible` lorsque requis ;
- `qemu-guest-agent` ;
- `cloud-init` ;
- `cloud-guest-utils` ;
- chrony ;
- outils de diagnostic de base ;
- durcissement raisonnable ;
- AppArmor ;
- auditd ;
- fail2ban SSH ;
- unattended-upgrades ;
- configuration journald ;
- sysctl de sécurité ;
- nftables installé et préparé, mais pas forcément activé.

Il ne doit pas contenir par défaut :

- NGINX ;
- PostgreSQL ;
- MariaDB ;
- Docker ;
- Podman ;
- Redis ;
- GitLab ;
- Nextcloud ;
- monitoring complet ;
- agents applicatifs spécialisés ;
- données propres à un clone ;
- secrets ;
- clés privées.

Les services spécialisés doivent être installés ensuite par des playbooks dédiés sur les clones.

---

## SSH

Le template Debian 13 Proxmox doit être construit avec un accès SSH par clé dès le départ.

Cloud-init doit injecter le `ciuser` et sa clé publique avant l'exécution d'Ansible.

État attendu :

```text
PasswordAuthentication no
PermitRootLogin no
PubkeyAuthentication yes
AuthenticationMethods publickey
```

Ne pas lancer le playbook de préparation tant que l'accès SSH par clé au compte technique n'est pas confirmé.

Toute modification SSH doit valider la configuration avant rechargement :

```bash
sshd -t
```

---

## Pare-feu

Ne pas activer un pare-feu générique dans un template sans confirmation explicite.

Pour le template Debian 13, `nftables` peut être installé et préparé, mais rester désactivé par défaut.

L’activation du pare-feu doit être faite sur un clone ou sur un serveur final, avec des règles adaptées à son rôle.

---

## Cloud-init

Cloud-init sert à donner l’identité initiale d’un clone :

- hostname ;
- utilisateur initial ;
- clé SSH ;
- adresse IP ;
- passerelle ;
- DNS ;
- agrandissement de la partition racine.

Cloud-init ne doit pas remplacer Ansible pour la configuration applicative.

Séparation attendue :

```text
Proxmox + cloud-init : identité initiale de la VM
Set-OPS + Ansible    : configuration réelle du serveur
```

---

## Nettoyage avant template

Le nettoyage final avant conversion en template doit être protégé par une confirmation explicite.

Exemple :

```bash
ansible-playbook -i instance/inventories/lab/hosts.yml playbooks/modeles_vm/debian13_proxmox_nettoyer.yml -e template_cleanup_confirm=true
```

Le nettoyage peut inclure :

- `cloud-init clean --logs` ;
- nettoyage du cache APT ;
- rotation ou purge contrôlée des journaux ;
- vidage de `/etc/machine-id` ;
- remise en place du lien `/var/lib/dbus/machine-id` ;
- suppression des historiques shell.

Ne jamais lancer ce nettoyage sur un serveur de production sans confirmation explicite.

---

## CHANGELOG

Chaque modification significative doit être inscrite dans `CHANGELOG.md`.

Format recommandé :

```markdown
## YYYY-MM-DD

### Ajouté
- ...

### Modifié
- ...

### Corrigé
- ...
```

Les corrections de rôles, handlers, playbooks et templates doivent être consignées.

---

## Stabilisation des changements

Après une série cohérente de changements validés, recommander un commit propre avant de poursuivre vers un nouveau chantier.

Avant de recommander un commit :

- vérifier l'état Git ;
- résumer les fichiers créés, modifiés, déplacés ou supprimés ;
- indiquer les validations exécutées ;
- signaler les validations non exécutées ;
- mentionner les risques ou limites connus.

Ne pas créer de commit sans demande explicite.

---

## Comportement attendu de Codex

Avant de modifier :

1. Lire `AGENTS.md`.
2. Lire `README.md`, `CHANGELOG.md` et `ansible.cfg` s’ils existent.
3. Vérifier l’état Git.
4. Inspecter les fichiers concernés.
5. Identifier la portée exacte de la demande.
6. Proposer le plus petit changement utile.
7. Préserver les conventions existantes.

Après modification :

1. Résumer les fichiers créés ou modifiés.
2. Indiquer les commandes de validation exécutées.
3. Signaler clairement ce qui n’a pas été testé.
4. Mettre à jour `CHANGELOG.md` si pertinent.
5. Ne pas affirmer que c’est prêt si la validation a échoué.

---

## Philosophie

Set-OPS est un outil d’exploitation réelle, pas une démonstration technique.

Priorités :

- reproductibilité ;
- sobriété ;
- clarté ;
- sécurité ;
- maintenance ;
- autonomie ;
- résilience.

La complexité doit toujours être justifiée par un bénéfice opérationnel clair.