From 8fac83bcdb4c3e2b44b8d2a2dbb7afcd0b8f48e7 Mon Sep 17 00:00:00 2001 From: Daniel Allaire Date: Sat, 20 Jun 2026 15:26:46 -0400 Subject: [PATCH] Documente la reprise Codex Claude pour Set-OPS --- CHANGELOG.md | 50 +++++++ CLAUDE.md | 249 +++++++++++++++++++++++++++++-- docs/MISE-A-JOUR-CODEX-CLAUDE.md | 197 ++++++++++++++++++++++++ 3 files changed, 484 insertions(+), 12 deletions(-) create mode 100644 docs/MISE-A-JOUR-CODEX-CLAUDE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c5f6e6e..156d216 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,3 +9,53 @@ - Rôles de hardening template-safe. - Playbook de vérification. - Playbook de nettoyage final avant conversion en template. +# CHANGELOG — Set-OPS + +## 2026-06-20 + +### Contexte +- Clarification : `Set-OPS` est le dépôt global d’exploitation Ansible de Chezlepro Inc. +- Clarification : le template Debian 13 Proxmox est un sous-ensemble du dépôt, pas sa finalité unique. +- Clarification : les services applicatifs spécialisés doivent être installés sur les clones par des playbooks dédiés, pas directement dans le template. + +### Ajouté +- Ajout des directives renforcées dans `AGENTS.md` : + - validation Ansible obligatoire ; + - vérification des handlers Ansible ; + - interdiction de déclarer un playbook prêt si `--syntax-check` échoue ; + - préférence pour les correctifs ciblés au lieu des régénérations massives ; + - rappel que `Set-OPS` ne doit pas être restructuré autour d’un seul besoin ponctuel. +- Ajout d’une logique de template Debian 13 Proxmox : + - `playbooks/vm_templates/debian13_proxmox_prepare.yml` ; + - `playbooks/vm_templates/debian13_proxmox_verify.yml` ; + - `playbooks/vm_templates/debian13_proxmox_cleanup.yml`. +- Ajout d’une couche de hardening template-safe : + - AppArmor ; + - auditd ; + - fail2ban SSH ; + - unattended-upgrades ; + - journald ; + - sysctl de sécurité ; + - nftables installé et préparé, mais désactivé par défaut dans le template. + +### Modifié +- Renforcement attendu de `CLAUDE.md` pour rappeler que `AGENTS.md` est la source d’autorité principale. +- Clarification du comportement attendu de Claude Code : + - lire l’existant avant modification ; + - vérifier `git status --short` ; + - ne pas faire de régénération massive sans demande explicite ; + - valider les playbooks touchés ; + - signaler les tests non exécutés ; + - mettre à jour `CHANGELOG.md` si pertinent. + +### Corrigé à appliquer +- Vérifier tous les rôles contenant `notify`. +- Ajouter les handlers manquants dans les rôles concernés, notamment : + - `roles/ssh_baseline/handlers/main.yml` ; + - `roles/ssh_hardening/handlers/main.yml`. + +### À valider +- Vérifier que chaque `notify` pointe vers un handler existant. +- Relancer le playbook de préparation du template. +- Lancer le playbook de vérification. +- Ne pas lancer le nettoyage final avant validation complète de la VM. diff --git a/CLAUDE.md b/CLAUDE.md index 164f9f2..535d134 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,19 +1,244 @@ # CLAUDE.md — Set-OPS -Claude Code doit lire et respecter `AGENTS.md`. +## Instruction principale -`AGENTS.md` est la source d'autorité principale. +Claude Code doit lire et respecter `AGENTS.md` avant toute modification. -Avant modification : +`AGENTS.md` est la source d’autorité principale du dépôt. -1. Lire `AGENTS.md`. -2. Lire `README.md`, `CHANGELOG.md` et `ansible.cfg`. -3. Vérifier `git status --short`. -4. Proposer le plus petit changement utile. +En cas de contradiction entre `CLAUDE.md` et `AGENTS.md`, suivre `AGENTS.md`. -Après modification : +--- -1. Résumer les fichiers modifiés. -2. Indiquer les commandes de validation. -3. Signaler ce qui n'a pas été testé. -4. Mettre à jour `CHANGELOG.md` si pertinent. +## Rôle du dépôt + +`Set-OPS` est le dépôt Ansible global d’exploitation de Chezlepro Inc. + +Le template Debian 13 Proxmox est seulement un sous-ensemble du dépôt. Ne pas restructurer tout le dépôt autour de ce seul chantier. + +--- + +## 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. + +--- + +## Avant toute modification + +Exécuter ou demander l’équivalent de : + +```bash +git status --short +find . -maxdepth 3 -type f | sort +``` + +Lire au minimum : + +```text +AGENTS.md +README.md +CHANGELOG.md +ansible.cfg +``` + +Lire aussi les fichiers directement concernés avant de les modifier. + +Ne pas remplacer massivement l’arborescence sans demande explicite. + +Préférer un correctif minimal ciblé. + +--- + +## Validation Ansible obligatoire + +Avant de dire qu’un changement est prêt, exécuter au minimum le `--syntax-check` du playbook touché. + +Pour le template Debian 13 Proxmox : + +```bash +ansible-playbook -i inventories/lab/hosts.yml playbooks/vm_templates/debian13_proxmox_prepare.yml --syntax-check +``` + +Si `ansible-lint` est disponible : + +```bash +ansible-lint +``` + +Si `ansible-lint` n’est pas disponible, le signaler clairement. + +Ne jamais déclarer un playbook prêt si la validation échoue. + +--- + +## 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 +``` + +Commandes 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. + +--- + +## Actions destructives + +Toute action destructrice ou risquée doit exiger une confirmation explicite. + +Exemple : + +```yaml +confirm_destructive_action: true +``` + +Sont considérées 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. + +--- + +## Template Debian 13 Proxmox + +Le template 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 ; +- hardening raisonnable ; +- AppArmor ; +- auditd ; +- fail2ban SSH ; +- unattended-upgrades ; +- journald ; +- sysctl de sécurité ; +- nftables installé et préparé, mais non activé par défaut. + +Il ne doit pas contenir par défaut : + +- NGINX ; +- PostgreSQL ; +- MariaDB ; +- Docker ; +- Podman ; +- Redis ; +- GitLab ; +- Nextcloud ; +- monitoring complet ; +- données propres à un clone ; +- secrets ; +- clés privées. + +--- + +## SSH + +Pendant la construction du template : + +```text +PasswordAuthentication yes +PermitRootLogin no +PubkeyAuthentication yes +``` + +État cible 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 le template sans confirmation explicite. + +`nftables` peut être installé et préparé, mais rester désactivé dans le template. + +L’activation doit être faite sur un clone ou un serveur final, avec des règles adaptées au rôle du serveur. + +--- + +## Cloud-init + +Cloud-init donne l’identité initiale d’un clone : + +- hostname ; +- utilisateur initial ; +- clé SSH ; +- IP ; +- passerelle ; +- DNS ; +- agrandissement de la partition racine. + +Cloud-init ne remplace pas Ansible. + +Séparation attendue : + +```text +Proxmox + cloud-init : identité initiale de la VM +Set-OPS + Ansible : configuration réelle du serveur +``` + +--- + +## Après modification + +Répondre avec : + +1. fichiers créés ; +2. fichiers modifiés ; +3. commandes de validation exécutées ; +4. résultat des validations ; +5. tests non exécutés ; +6. limites connues ; +7. entrée `CHANGELOG.md` ajoutée ou raison de l’absence d’entrée. + +Ne pas dire que c’est prêt si ce n’est pas validé. diff --git a/docs/MISE-A-JOUR-CODEX-CLAUDE.md b/docs/MISE-A-JOUR-CODEX-CLAUDE.md new file mode 100644 index 0000000..3eab9a5 --- /dev/null +++ b/docs/MISE-A-JOUR-CODEX-CLAUDE.md @@ -0,0 +1,197 @@ +# Mise à jour pour Codex et Claude Code — Set-OPS + +## État du dépôt + +`Set-OPS` est le dépôt Ansible global d’exploitation de Chezlepro Inc. + +Il ne sert pas seulement à créer un template Proxmox. Il doit contenir progressivement les playbooks, rôles, inventaires et templates nécessaires à tous les systèmes de Chezlepro Inc. + +Le chantier en cours est le template Debian 13 Proxmox. + +--- + +## Fichiers de gouvernance + +Les fichiers suivants doivent être lus avant toute modification : + +```text +AGENTS.md +CLAUDE.md +README.md +CHANGELOG.md +ansible.cfg +``` + +`AGENTS.md` est la source d’autorité principale. + +--- + +## État fonctionnel visé pour le template Debian 13 + +Le template Debian 13 Proxmox doit contenir : + +- Debian minimal ; +- SSH ; +- sudo ; +- compte `ansible` ; +- sudo NOPASSWD pour `ansible` ; +- `qemu-guest-agent` ; +- `cloud-init` ; +- `cloud-guest-utils` ; +- chrony ; +- outils de diagnostic ; +- AppArmor ; +- auditd ; +- fail2ban SSH ; +- unattended-upgrades ; +- journald ; +- sysctl de sécurité ; +- nftables installé et préparé, mais désactivé par défaut. + +Il ne doit pas contenir : + +- NGINX ; +- PostgreSQL ; +- MariaDB ; +- Docker ; +- Podman ; +- Redis ; +- GitLab ; +- Nextcloud ; +- monitoring complet ; +- secrets ; +- clés privées ; +- données propres à un clone. + +--- + +## Incident récent à corriger + +Le playbook : + +```text +playbooks/vm_templates/debian13_proxmox_prepare.yml +``` + +a échoué sur un handler manquant : + +```text +ERROR! The requested handler 'Validate and reload ssh' was not found +``` + +Le problème est relié à des rôles contenant : + +```yaml +notify: Validate and reload ssh +``` + +sans handler local correspondant. + +Rôles à vérifier en priorité : + +```text +roles/ssh_baseline/ +roles/ssh_hardening/ +``` + +Chaque rôle utilisant `notify` doit avoir son propre fichier : + +```text +roles//handlers/main.yml +``` + +--- + +## Correctif minimal attendu + +Ne pas régénérer tout le dépôt. + +Créer ou corriger : + +```text +roles/ssh_baseline/handlers/main.yml +roles/ssh_hardening/handlers/main.yml +``` + +Contenu attendu : + +```yaml +--- +- name: Validate and reload ssh + block: + - name: Valider la configuration SSH + ansible.builtin.command: sshd -t + changed_when: false + + - name: Recharger SSH + ansible.builtin.systemd: + name: ssh + state: reloaded +``` + +Puis vérifier tous les `notify` : + +```bash +find roles -path '*/tasks/*.yml' -exec grep -H "notify:" {} \; +find roles -path '*/handlers/main.yml' -print +``` + +--- + +## Validation obligatoire + +Après correction : + +```bash +ansible-playbook -i inventories/lab/hosts.yml playbooks/vm_templates/debian13_proxmox_prepare.yml --syntax-check +``` + +Puis relancer : + +```bash +ansible-playbook -i inventories/lab/hosts.yml playbooks/vm_templates/debian13_proxmox_prepare.yml +``` + +Puis vérifier : + +```bash +ansible-playbook -i inventories/lab/hosts.yml playbooks/vm_templates/debian13_proxmox_verify.yml +``` + +--- + +## Nettoyage final + +Ne lancer le nettoyage final que lorsque la VM est validée : + +```bash +ansible-playbook -i inventories/lab/hosts.yml playbooks/vm_templates/debian13_proxmox_cleanup.yml -e confirm_template_cleanup=true +``` + +Ensuite seulement : + +```bash +sudo shutdown -h now +``` + +Puis côté Proxmox : + +```bash +qm template VMID +``` + +--- + +## Règle de conduite + +Ne pas faire de régénération massive. + +Lire l’existant. + +Corriger petit. + +Valider. + +Mettre à jour `CHANGELOG.md`. + +Résumer clairement ce qui a été fait et ce qui n’a pas été testé.