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.

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.