diff --git a/AGENTS.md b/AGENTS.md index 6ff5d70..605ff60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,9 +4,9 @@ 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. +`Set-OPS` est le dépôt global d’exploitation de Chezlepro Inc. -Ce dépôt doit permettre de reconstruire progressivement l’environnement serveur à partir de modèles propres, principalement basés sur Debian 13. +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. --- @@ -22,170 +22,17 @@ Tout changement significatif doit être consigné dans `CHANGELOG.md`. --- -## Principes de travail +## Principes 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. +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. --- @@ -196,123 +43,319 @@ Ne jamais commiter : - mots de passe ; - clés privées SSH ; - tokens API ; -- secrets Ansible Vault non chiffrés ; +- secrets non chiffrés ; - fichiers `.env` sensibles ; -- exports de configuration contenant des secrets ; - certificats privés ; - backups réels ; -- fichiers de production non anonymisés. +- exports de production non anonymisés. -Créer ou maintenir un `.gitignore` adapté. - -Toute variable sensible doit être placée dans un mécanisme approprié : +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 externe explicitement approuvé. +- gestionnaire de secrets approuvé. --- -## SSH +## Actions destructives -É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 : +Toute action destructive doit exiger une variable explicite, par exemple : ```yaml confirm_destructive_action: true ``` -Et refuser l’exécution autrement. +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. --- -## Documentation +## Règle de modification du dépôt -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 : +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-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. +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. --- @@ -335,30 +378,35 @@ Format recommandé : - ... ``` +Les corrections de rôles, handlers, playbooks et templates doivent être consignées. + --- ## 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. +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 modifiés. -2. Indiquer les commandes de validation. +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 +## Philosophie -Set-OPS doit rester un outil d’exploitation réelle, pas une démonstration technique. +Set-OPS est un outil d’exploitation réelle, pas une démonstration technique. Priorités :