Set-OPS/AGENTS.md

# 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.