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 :

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 :

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 :

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 :

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 :

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 :

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 :

inventories/
playbooks/
roles/
templates/
files/
scripts/
docs/

Les playbooks peuvent être classés par domaine :

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 :

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 :

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 :

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 :

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 :

serveur_debian

Les groupes spécialisés doivent s'ajouter selon les besoins réels, par exemple :

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 :

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

Exemples :

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 :

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 :

ssh_durcissement_port: 22
nftables_socle_enabled: false
fail2ban_ssh_enabled: true

Séparer clairement :

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 :

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 :

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 :

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 :

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

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