373 lines
8 KiB
Markdown
373 lines
8 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.
|
||
|
||
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.
|