# 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. Objectif principal : produire une infrastructure reproductible, lisible, sobre, sécuritaire et administrable sans dépendance inutile au cloud. Ce dépôt doit permettre de reconstruire progressivement l’environnement serveur à partir de modèles propres, principalement basés sur Debian 13. --- ## 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 de travail 1. Toujours lire l’existant avant de modifier. 2. Ne jamais présumer de l’inventaire réel sans le vérifier. 3. Ne jamais introduire de secret en clair. 4. Ne jamais casser l’idempotence Ansible. 5. Ne jamais exécuter d’action destructive sans confirmation explicite. 6. Préférer la simplicité à l’ingénierie excessive. 7. Documenter ce qui est utile à l’exploitation réelle. 8. Produire des playbooks relisibles par un humain fatigué en situation d’incident. --- ## Style Ansible attendu Les playbooks doivent être : - idempotents ; - lisibles ; - découpés en rôles lorsque pertinent ; - compatibles avec 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.lineinfile` - `ansible.builtin.file` - `ansible.builtin.user` - `ansible.builtin.group` - `ansible.builtin.systemd` Éviter les commandes `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 recommandée Le dépôt doit tendre progressivement vers cette structure : ```text Set-OPS/ ├── AGENTS.md ├── README.md ├── CHANGELOG.md ├── ansible.cfg ├── inventories/ │ ├── lab/ │ │ ├── hosts.yml │ │ └── group_vars/ │ └── production/ │ ├── hosts.yml │ └── group_vars/ ├── playbooks/ │ ├── bootstrap.yml │ ├── baseline.yml │ ├── hardening.yml │ ├── updates.yml │ ├── nginx.yml │ ├── monitoring.yml │ └── users.yml ├── roles/ │ ├── common/ │ ├── users/ │ ├── ssh/ │ ├── sudo/ │ ├── qemu_guest_agent/ │ ├── chrony/ │ ├── firewall/ │ ├── unattended_updates/ │ ├── nginx/ │ ├── monitoring_agent/ │ └── vm_template_cleanup/ ├── templates/ ├── files/ ├── scripts/ └── docs/ ``` Ne pas créer toute cette structure inutilement d’un seul coup. La créer selon les besoins réels. --- ## Conventions de nommage Utiliser des noms clairs, sobres et prévisibles. Exemples de playbooks : ```text baseline.yml hardening.yml debian13-template.yml nginx-static-site.yml monitoring-agent.yml ``` Exemples de rôles : ```text roles/common roles/ssh roles/sudo roles/nginx roles/qemu_guest_agent ``` Exemples de variables : ```yaml chezlepro_timezone: "America/Toronto" chezlepro_admin_user: "ansible" chezlepro_ssh_port: 22 ``` --- ## Cibles connues Contexte d’exploitation Chezlepro Inc. : - hyperviseurs Proxmox ; - stockage TrueNAS iSCSI ; - VM Debian 13 ; - administration par Ansible ; - préférence pour logiciels libres ; - préférence pour services sobres, locaux, documentés ; - éviter les dépendances cloud ; - usage de comptes techniques dédiés ; - SSH par clé à terme ; - compte `ansible` avec sudo sans mot de passe lorsque nécessaire. --- ## Modèle Debian 13 de base Les rôles liés au modèle Debian 13 doivent viser : - système minimal ; - pas d’environnement graphique ; - SSH installé ; - `qemu-guest-agent` installé et actif ; - `sudo` installé ; - utilisateur `ansible` présent ; - sudo NOPASSWD pour `ansible`, lorsque demandé ; - timezone correcte ; - hostname propre ; - mises à jour appliquées ; - logs et caches nettoyables avant conversion en template ; - aucune clé privée ; - aucun secret ; - aucune donnée propre à une VM clonée. --- ## Sécurité Ne jamais commiter : - mots de passe ; - clés privées SSH ; - tokens API ; - secrets Ansible Vault non chiffrés ; - fichiers `.env` sensibles ; - exports de configuration contenant des secrets ; - certificats privés ; - backups réels ; - fichiers de production non anonymisés. Créer ou maintenir un `.gitignore` adapté. Toute variable sensible doit être placée dans un mécanisme approprié : - Ansible Vault ; - fichier local non versionné ; - secret injecté hors dépôt ; - gestionnaire de secrets externe explicitement approuvé. --- ## SSH État transitoire accepté pendant la construction : ```text PasswordAuthentication yes ``` État cible recommandé : ```text PermitRootLogin no PubkeyAuthentication yes PasswordAuthentication no ``` Ne jamais désactiver l’authentification par mot de passe avant d’avoir confirmé que l’accès par clé fonctionne. --- ## Sudo Le compte technique `ansible` peut être configuré ainsi : ```text ansible ALL=(ALL) NOPASSWD:ALL ``` Cette règle doit être placée dans : ```text /etc/sudoers.d/90-ansible ``` Toujours valider avec : ```bash visudo -cf /etc/sudoers.d/90-ansible ``` --- ## Playbooks destructifs Toute action pouvant causer une perte d’accès ou de données doit être protégée. Exemples d’actions destructives : - suppression de paquets critiques ; - modification SSH bloquante ; - redémarrage massif ; - formatage disque ; - modification de partitions ; - suppression d’utilisateurs ; - modification firewall ; - purge de données ; - changement réseau pouvant couper l’accès. Pour ces actions, exiger une variable explicite : ```yaml confirm_destructive_action: true ``` Et refuser l’exécution autrement. --- ## Documentation Chaque rôle important doit contenir au minimum : ```text roles/nom_du_role/README.md roles/nom_du_role/defaults/main.yml roles/nom_du_role/tasks/main.yml ``` Le README du rôle doit expliquer : - ce que le rôle fait ; - sur quelles distributions il est prévu ; - les variables principales ; - les effets de bord ; - les commandes de test. --- ## Tests minimaux Avant de proposer un changement comme terminé, vérifier autant que possible : ```bash ansible-playbook --syntax-check playbooks/nom.yml ansible-playbook -i inventories/lab/hosts.yml playbooks/nom.yml --check ansible-lint ``` Si `ansible-lint` n’est pas disponible, le mentionner clairement sans inventer un résultat. --- ## CHANGELOG Chaque modification significative doit être inscrite dans `CHANGELOG.md`. Format recommandé : ```markdown ## YYYY-MM-DD ### Ajouté - ... ### Modifié - ... ### Corrigé - ... ``` --- ## Comportement attendu de Codex Avant de modifier : 1. Lire `README.md`, `CHANGELOG.md`, `ansible.cfg` et l’arborescence existante. 2. Identifier la portée exacte de la demande. 3. Proposer le plus petit changement utile. 4. Préserver les conventions existantes. 5. Ne pas réorganiser massivement le dépôt sans demande explicite. Après modification : 1. Résumer les fichiers modifiés. 2. Indiquer les commandes de validation. 3. Signaler clairement ce qui n’a pas été testé. 4. Mettre à jour `CHANGELOG.md` si pertinent. --- ## Philosophie Set-OPS Set-OPS doit rester 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.