# 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. --- ## 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. --- ## 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 inventories/lab/hosts.yml playbooks/vm_templates/debian13_proxmox_prepare.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/ ├── baseline/ ├── hardening/ ├── maintenance/ ├── monitoring/ ├── networking/ ├── proxmox/ ├── vm_templates/ ├── 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. --- ## 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 ; - hardening 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 Pendant la construction du template, l’état transitoire accepté est : ```text PasswordAuthentication yes PermitRootLogin no PubkeyAuthentication yes ``` État cible recommandé après validation des clés SSH : ```text PasswordAuthentication no PermitRootLogin no PubkeyAuthentication yes ``` Ne jamais désactiver l’authentification par mot de passe avant d’avoir confirmé que l’accès par clé fonctionne. 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 inventories/lab/hosts.yml playbooks/vm_templates/debian13_proxmox_cleanup.yml -e confirm_template_cleanup=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. --- ## 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.