421 lines
9.4 KiB
Markdown
421 lines
9.4 KiB
Markdown
# 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.
|