Playbooks mixtes : main.yml + vault.yml par groupe avec convention vault_*

La meilleure structure pour un projet Ansible mature : pour chaque groupe d’inventaire, deux fichiers côte à côte — main.yml qui contient les variables publiques (port, version, environnement) et vault.yml qui contient uniquement les secrets (chiffré complet). Ansible les fusionne automatiquement, et la convention vault_* rend la sensibilité visible dans le code.

À la fin, vous saurez structurer un group_vars/ industriel, garder des diffs Git lisibles sur les variables publiques, et limiter le périmètre du mot de passe vault aux modifications réellement sensibles.

Pressé ? La structure group_vars industrielle

inventory/
├── hosts.yml
└── group_vars/
    ├── all/
    │   ├── main.yml         # variables publiques de "all" (clair)
    │   └── vault.yml        # secrets de "all" (chiffré)
    ├── webservers/
    │   ├── main.yml         # variables publiques webservers (clair)
    │   └── vault.yml        # secrets webservers (chiffré)
    └── prod/
        ├── main.yml
        └── vault.yml

# group_vars/all/main.yml — VARIABLES PUBLIQUES (lisible en revue Git)
---
http_port: 80
http_max_clients: 1024
log_level: info

# Indirection vers les secrets (qui sont dans vault.yml)
db_password: "{{ vault_db_password }}"
api_token: "{{ vault_api_token }}"

# group_vars/all/vault.yml — CHIFFRÉ avec ansible-vault encrypt
---
vault_db_password: "vraivaleurchiffree"
vault_api_token: "abc123token"

Sécurité non négociable :

• Préférer 2 fichiers (main + vault) à 1 fichier mixte — diffs Git lisibles sur les 47 variables publiques, le mot de passe vault n’est nécessaire que pour modifier les vrais secrets.
• Convention vault_* stricte — chaque variable chiffrée porte le préfixe, l’indirection est dans main.yml. grep "vault_" . liste tous les secrets du repo en 1 commande.
• Permission 0644 pour main.yml, 0600 pour vault.yml côté contrôle local — un linter peut vérifier que tout vault.yml a 0600.
• CI/CD : vérifier qu’il n’y a pas de mot de passe en clair dans les main.yml via git diff --cached | grep -E "password|secret|token" | grep -v "vault_".

Ce que vous allez apprendre

• Pattern group_vars/<groupe>/main.yml + vault.yml : structure et règles de fusion.
• Convention de nommage vault_* pour distinguer visuellement une variable sensible.
• Fusion automatique par Ansible : les deux fichiers forment un seul namespace.
• Diff Git : pourquoi cette structure produit des diffs lisibles.
• Lecture sans déchiffrer : qui peut lire main.yml sans avoir le mot de passe vault.
• Rotation localisée : ne rote que les vault.yml du groupe concerné.

Prérequis

• Avoir lu Introduction Ansible Vault et encrypt_string.
• Comprendre group_vars/ (voir Inventaires).

Le pattern en une image

inventory/
├── hosts.yml
└── group_vars/
    ├── all/
    │   ├── main.yml        ← variables publiques partagées (clair)
    │   └── vault.yml       ← secrets partagés (CHIFFRÉ COMPLET)
    ├── webservers/
    │   ├── main.yml        ← config publique webservers (clair)
    │   └── vault.yml       ← secrets webservers (CHIFFRÉ COMPLET)
    └── dbservers/
        ├── main.yml
        └── vault.yml

Règle d’or : pour un groupe donné, Ansible fusionne automatiquement tous les fichiers YAML présents dans group_vars/<groupe>/. Un host de webservers voit donc :

• les variables de all/main.yml + all/vault.yml (héritage)
• les variables de webservers/main.yml + webservers/vault.yml (spécifique)

Convention : préfixer les variables vault par vault_* (ex: vault_admin_token, vault_db_password, vault_web_secret). Permet un coup d’œil rapide pour repérer les valeurs sensibles dans tout le code.

Pourquoi pas un seul fichier complètement chiffré

Trois inconvénients du fichier unique chiffré :

• Diffs Git illisibles : modifier http_port: 80 → 8080 produit un blob hex aléatoire de 200 lignes. Impossible à reviewer.
• Périmètre vault élargi : ajouter une variable publique demande le mot de passe.
• Lecture en revue : impossible de comprendre la config sans déchiffrer.

Le pattern mixte résout les trois en mettant la frontière claire/chiffré au niveau du fichier, pas au niveau de la variable.

Étape 1 — Préparer la structure

cd labs/vault/playbooks-mixtes/

mkdir -p inventory/group_vars/all
mkdir -p inventory/group_vars/webservers

# all/main.yml — variables PUBLIQUES partagées
cat > inventory/group_vars/all/main.yml <<'EOF'
deployment_environment: lab80
EOF

# webservers/main.yml — config publique
cat > inventory/group_vars/webservers/main.yml <<'EOF'
http_port: 80
worker_count: 4
EOF

Ces fichiers restent en clair. On peut les cat, les diff, les commiter sans souci.

Étape 2 — Créer les fichiers de secrets

# all/vault.yml — secrets PARTAGÉS
cat > inventory/group_vars/all/vault.yml <<'EOF'
vault_admin_token: "lab80-admin-token-2026"
EOF

# webservers/vault.yml — secrets WEBSERVERS
cat > inventory/group_vars/webservers/vault.yml <<'EOF'
vault_web_secret: "web_secret_lab80_xyz"
vault_web_db_password: "WebDbPassLab80!"
EOF

Pour l’instant non chiffrés. On va les chiffrer dans l’étape suivante.

Convention vault_* : toutes les variables sensibles sont préfixées. Un grep rapide (grep -r "vault_" .) liste tous les secrets utilisés dans le projet.

Étape 3 — Chiffrer chaque vault.yml

ansible-vault encrypt \
  inventory/group_vars/all/vault.yml \
  inventory/group_vars/webservers/vault.yml \
  --vault-password-file=.vault_password

Vérifier :

head -1 inventory/group_vars/all/vault.yml
# → $ANSIBLE_VAULT;1.1;AES256

head -1 inventory/group_vars/webservers/main.yml
# → http_port: 80    (clair, intact)

Étape 4 — Lancer le playbook

Le playbook ne fait aucune distinction entre variables claires et chiffrées. Ansible s’occupe de tout.

playbook.yml

- name: Lab 80 — Playbook mixte
  hosts: webservers
  become: true
  gather_facts: false

  tasks:
    - name: Pose un fichier qui combine variables claires et chiffrées
      ansible.builtin.copy:
        dest: /tmp/lab80-mixte.txt
        mode: "0600"
        content: |
          === Lab 80 — playbook mixte ===

          Variables PUBLIQUES (group_vars/<group>/main.yml) :
            deployment_environment: {{ deployment_environment }}
            http_port: {{ http_port }}
            worker_count: {{ worker_count }}

          Secrets CHIFFRÉS (group_vars/<group>/vault.yml) :
            vault_admin_token starts: {{ vault_admin_token[:5] }}
            vault_web_secret starts: {{ vault_web_secret[:5] }}
            vault_web_db_password length: {{ vault_web_db_password | length }}

ansible-playbook -i inventory/hosts.yml \
  --vault-password-file=.vault_password \
  playbook.yml

Vérifier côté cible :

ssh ansible@web1.lab "sudo cat /tmp/lab80-mixte.txt"

Sortie : 6 variables accessibles transparentement depuis un seul namespace, dont 3 chiffrées et 3 claires. La {{ var }} est strictement la même syntaxe pour les deux.

Bénéfice n°1 — diffs Git lisibles

Modifier le port HTTP :

sed -i 's/http_port: 80/http_port: 8080/' inventory/group_vars/webservers/main.yml
git diff

Sortie :

http_port: 80
http_port: 8080

Une ligne diffable, immédiatement compréhensible en revue de code. Avec un fichier unique chiffré, le diff aurait montré un blob hex de 100+ lignes.

Bénéfice n°2 — lecture sans déchiffrer

Un développeur qui n’a pas le mot de passe vault peut quand même lire :

cat inventory/group_vars/webservers/main.yml
# → http_port: 8080
# → worker_count: 4

Il comprend la config, peut proposer des changements sur les variables publiques (worker_count: 8 par exemple), sans accès aux secrets. Le périmètre du mot de passe vault est limité aux personnes qui doivent réellement modifier les secrets.

Bénéfice n°3 — rotation localisée

Compromission suspectée des secrets webservers uniquement ?

# Modifier seul vault.yml de webservers, ignorer all/
ansible-vault edit inventory/group_vars/webservers/vault.yml \
  --vault-password-file=.vault_password
# (changer les valeurs, sauver)

Aucun toucher à all/vault.yml ni dbservers/vault.yml. La rotation est chirurgicale.

Convention vault_* — pourquoi ce préfixe précis

Trois alternatives ont été essayées par la communauté Ansible :

Préfixe	Avantages	Inconvénients
vault_*	Court, parle à tout Ansible-iste	Aucun
_secret_*	Souligne la sensibilité	Underscore initial = convention “privé” en Python, prête à confusion
secure_*	Lisible	Trop générique, déjà utilisé en sysadmin

Glissez pour voir

vault_* est devenu la convention de facto dans la doc officielle Red Hat et la majorité des rôles Galaxy. Le respecter facilite la lecture par d’autres développeurs et la portabilité des rôles.

Que se passe-t-il si la même variable est définie dans main et vault ?

Ansible suit la précédence standard : le fichier traité en dernier par ordre alphabétique gagne. Avec main.yml et vault.yml, vault.yml gagne car v > m alphabétiquement.

C’est généralement le comportement souhaité : si on définit db_password dans main (placeholder pour debug local) et dans vault (vraie valeur prod), la valeur vault l’emporte.

À tester en cas de doute :

ansible -i inventory/hosts.yml all -m debug -a "var=ma_variable" \
  --vault-password-file=.vault_password

Lab pratique

Le lab vault/playbooks-mixtes du repo ansible-training reproduit ce parcours avec 4 tests pytest qui valident :

• Les fichiers main.yml sont en clair, vault.yml chiffrés.
• Les variables claires et chiffrées sont toutes accessibles dans le playbook.
• La convention vault_* est respectée.
• Le diff Git sur une variable publique reste lisible.

Suivre : labs/vault/playbooks-mixtes/README.md.

Pièges courants

• Mauvais emplacement de group_vars/ : doit être au même niveau que l’inventaire (inventory/group_vars/), pas à la racine du projet. Sinon Ansible ne charge pas les variables.
• Oubli de vault_* : un secret nommé db_password (sans préfixe) reste accessible mais on perd la lecture rapide de qui est sensible.
• Variables dupliquées entre main et vault : techniquement OK (vault gagne), mais source de confusion. Garder une seule définition.
• group_vars/all/vault.yml non chiffré : oubli classique. Vérifier head -1 inventory/group_vars/*/vault.yml après chaque modification.

À retenir

• Pattern <groupe>/main.yml + vault.yml : variables publiques d’un côté, secrets de l’autre.
• Convention vault_* rend la sensibilité visible dans tout le code (recherche grep).
• Ansible fusionne automatiquement les deux fichiers — un seul namespace côté playbook.
• Diffs Git lisibles sur les variables publiques (changements quotidiens).
• Périmètre vault minimal : seules les personnes qui modifient des secrets ont besoin du mot de passe.
• Rotation localisée : changer un mot de passe d’un seul groupe sans toucher aux autres.

Prochaines étapes

Vault dans les rôles defaults/main.yml + vars/main.yml chiffré : pattern d'indirection vault_* dans un rôle.

Intégration HashiCorp Vault Quand externaliser les secrets vers un secret manager dédié.

Multi-environnements vault-id Combiner ce pattern avec --vault-id par environnement (dev, prod).

Lab 80 sur GitHub Suivre le lab pas à pas avec tests pytest automatisés.

×

📖 Voir la documentation →