Renforce les directives AGENTS pour Set-OPS
This commit is contained in:
parent
1823341c94
commit
64c016d92c
1 changed files with 312 additions and 264 deletions
576
AGENTS.md
576
AGENTS.md
|
|
@ -4,9 +4,9 @@
|
|||
|
||||
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.
|
||||
`Set-OPS` est le dépôt global d’exploitation de Chezlepro Inc.
|
||||
|
||||
Ce dépôt doit permettre de reconstruire progressivement l’environnement serveur à partir de modèles propres, principalement basés sur Debian 13.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -22,170 +22,17 @@ Tout changement significatif doit être consigné dans `CHANGELOG.md`.
|
|||
|
||||
---
|
||||
|
||||
## Principes de travail
|
||||
## Principes
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -196,123 +43,319 @@ Ne jamais commiter :
|
|||
- mots de passe ;
|
||||
- clés privées SSH ;
|
||||
- tokens API ;
|
||||
- secrets Ansible Vault non chiffrés ;
|
||||
- secrets non chiffrés ;
|
||||
- fichiers `.env` sensibles ;
|
||||
- exports de configuration contenant des secrets ;
|
||||
- certificats privés ;
|
||||
- backups réels ;
|
||||
- fichiers de production non anonymisés.
|
||||
- exports de production non anonymisés.
|
||||
|
||||
Créer ou maintenir un `.gitignore` adapté.
|
||||
|
||||
Toute variable sensible doit être placée dans un mécanisme approprié :
|
||||
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 externe explicitement approuvé.
|
||||
- gestionnaire de secrets approuvé.
|
||||
|
||||
---
|
||||
|
||||
## SSH
|
||||
## Actions destructives
|
||||
|
||||
É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 :
|
||||
Toute action destructive doit exiger une variable explicite, par exemple :
|
||||
|
||||
```yaml
|
||||
confirm_destructive_action: true
|
||||
```
|
||||
|
||||
Et refuser l’exécution autrement.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
## Règle de modification du dépôt
|
||||
|
||||
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 :
|
||||
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-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.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -335,30 +378,35 @@ Format recommandé :
|
|||
- ...
|
||||
```
|
||||
|
||||
Les corrections de rôles, handlers, playbooks et templates doivent être consignées.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
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 modifiés.
|
||||
2. Indiquer les commandes de validation.
|
||||
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
|
||||
## Philosophie
|
||||
|
||||
Set-OPS doit rester un outil d’exploitation réelle, pas une démonstration technique.
|
||||
Set-OPS est un outil d’exploitation réelle, pas une démonstration technique.
|
||||
|
||||
Priorités :
|
||||
|
||||
|
|
|
|||
Reference in a new issue