Chezlepro/Set-OPS
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
This repository has been archived on 2026-06-26. You can view files and clone it, but cannot push or open issues or pull requests.
Set-OPS/AGENTS.md

9.4 KiB
Raw Blame History

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 :

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 :

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 :

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 :

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 :

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 :

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 :

inventories/
playbooks/
roles/
templates/
files/
scripts/
docs/

Les playbooks peuvent être classés par domaine :

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 :

PasswordAuthentication yes
PermitRootLogin no
PubkeyAuthentication yes

État cible recommandé après validation des clés SSH :

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 :

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 :

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 :

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é :

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