group_vars et host_vars : structurer les variables d'inventaire Ansible

group_vars/ et host_vars/ sont les emplacements standard où Ansible cherche automatiquement les variables liées à votre inventaire. Pas besoin de vars_files:, pas besoin de --extra-vars — il suffit que les fichiers soient bien placés et nommés selon une convention stricte. C’est cette convention qui rend votre inventaire maintenable au fil du temps.

Cette page couvre l’organisation de ces dossiers, la précédence quand une même variable est définie à plusieurs niveaux, et le pattern dossier (un dossier par groupe au lieu d’un fichier) pour des projets qui grandissent.

inventory/
├── hosts.yml                          # inventaire principal
├── group_vars/
│   ├── all.yml                        # variables communes à tous
│   ├── all/
│   │   ├── common.yml                 # variantes : split par thème
│   │   └── vault.yml                  # SECRETS chiffrés Vault
│   ├── webservers.yml                 # variables du groupe webservers
│   └── webservers/                    # ou dossier (si beaucoup)
│       ├── nginx.yml
│       └── vault.yml
└── host_vars/
    ├── web1.lab.yml                   # override individuel pour web1
    └── db1.lab/
        └── vault.yml                  # secrets spécifiques à db1

Précédence (du plus faible au plus fort) :

group_vars/all.yml (niveau 5)
group_vars/<groupe>.yml (niveau 6)
host_vars/<host>.yml (niveau 7)

Sécurité non négociable :

Pattern group_vars/<group>/vault.yml chiffré pour TOUS les secrets — jamais de credentials en clair dans group_vars/all.yml.
Placer group_vars/ et host_vars/ À CÔTÉ de l’inventaire (inventory/hosts.yml + inventory/group_vars/). Ailleurs = ignoré silencieusement.
Préfixer les variables (webserver_port, jamais port) — sans préfixe, deux groupes qui définissent port se marchent dessus.
host_vars/ réservé aux overrides individuels — si vous avez beaucoup de variables dans host_vars/, promouvoir la majorité dans group_vars/.

Ce que vous allez apprendre

Placer correctement group_vars/ et host_vars/ à côté de l’inventaire.
Définir une variable au niveau groupe ou au niveau host.
Comprendre la précédence : host_vars > group_vars/<groupe> > group_vars/all.
Splitter en plusieurs fichiers via le pattern dossier (group_vars/<groupe>/main.yml + vault.yml).
Vérifier la résolution avec ansible-inventory --host.

Prérequis

Avoir lu Inventaire statique YAML.
Connaître la commande ansible-inventory --host <host>.

Où placer les dossiers `group_vars/` et `host_vars/`

Ansible cherche ces dossiers à côté du fichier d’inventaire, pas à côté du playbook :

ma_formation/
├── ansible.cfg
├── playbooks/
│   └── deploy.yml
└── inventory/
    ├── hosts.yml              ← l'inventaire
    ├── group_vars/            ← variables par groupe
    │   ├── all.yml            ← tous les hôtes
    │   ├── webservers.yml
    │   └── dbservers.yml
    └── host_vars/             ← variables par host
        ├── web1.lab.yml
        └── db1.lab.yml

Règle stricte : group_vars/ et host_vars/ doivent être soit dans le même dossier que l’inventaire, soit dans le dossier du playbook. Si vous les mettez ailleurs, Ansible ne les trouve pas — sans erreur explicite, juste des variables manquantes.

Le groupe spécial `all`

group_vars/all.yml est appliqué à tous les hôtes de l’inventaire — c’est le fallback quand aucune variable plus spécifique n’est définie.

---
admin_email: ops@example.com
ntp_server: ntp.lab
backup_retention_days: 30

Toutes vos machines (webservers, dbservers, control…) reçoivent ces 3 variables. Idéal pour des paramètres organisationnels qui ne dépendent pas du rôle de la machine.

Variables par groupe

Pour des paramètres spécifiques à un rôle (web vs db vs LB), créer un fichier par groupe :

---
http_port: 8080
worker_processes: 4
nginx_max_body_size: 10m

Toutes les machines du groupe webservers (web1, web2…) reçoivent ces 3 variables. Les machines hors du groupe (db1) ne les voient pas.

Variables par host

Pour une exception ponctuelle sur un seul host :

---
http_port: 9090       # web1 écoute sur 9090, pas 8080
ssl_cert: /etc/pki/web1.lab.crt

web1.lab reçoit http_port: 9090 (override de webservers.yml) et ssl_cert: .... web2.lab reste sur http_port: 8080.

Précédence — la règle “le plus local gagne”

Quand la même variable est définie à plusieurs niveaux, Ansible applique cette hiérarchie (de la plus faible à la plus forte) :

Priorité	Source	Exemple
1 (faible)	`group_vars/all.yml`	`app_port: 80`
2	`group_vars/<groupe parent>.yml`	`app_port: 8080` (webservers)
3	`group_vars/<groupe enfant>.yml`	`app_port: 8443` (sous-groupe)
4 (forte)	`host_vars/<host>.yml`	`app_port: 9090` (web1)

Démonstration dans le lab inventaires/group-vars-host-vars : la même variable app_port définie à 3 niveaux donne 3 valeurs différentes selon le host :

$ ansible-inventory --host web1.lab | grep app_port
    "app_port": 9090            # host_vars/web1.lab.yml gagne

$ ansible-inventory --host web2.lab | grep app_port
    "app_port": 8080            # group_vars/webservers.yml gagne (pas de host_vars)

$ ansible-inventory --host db1.lab | grep app_port
    "app_port": 80              # group_vars/all.yml (fallback)

Pattern dossier — splitter en plusieurs fichiers

Quand group_vars/webservers.yml dépasse 50 lignes, le pattern dossier rend la lecture plus propre :

inventory/
├── hosts.yml
└── group_vars/
    └── webservers/
        ├── main.yml         ← variables principales
        ├── network.yml      ← config réseau
        └── vault.yml        ← secrets chiffrés Ansible Vault

Ansible fusionne automatiquement tous les .yml du dossier webservers/. Aucun ordre garanti — donc pas de variable redéfinie entre fichiers (sinon comportement aléatoire). Convention : un fichier par thème (réseau, sécurité, app, secrets).

http_port: 8080
worker_processes: 4

internal_subnet: 10.10.20.0/24
external_dns: 8.8.8.8

# group_vars/webservers/vault.yml  (chiffré par ansible-vault)
$ANSIBLE_VAULT;1.1;AES256
3133...

Mandatory pour les secrets : isoler dans vault.yml chiffré séparément du reste — vous pouvez ainsi lire le main.yml sans déchiffrer.

Vérifier la résolution

ansible-inventory --host <host> est l’outil pour voir toutes les variables résolues :

ansible-inventory --host web1.lab

Sortie tronquée :

{
  "ansible_host": "10.10.20.21",
  "ansible_user": "ansible",
  "app_port": 9090,
  "http_port": 9090,
  "ssl_cert": "/etc/pki/web1.lab.crt",
  "worker_processes": 4
}

Vous voyez toutes les variables résolues, peu importe leur source. Indispensable pour debugger un override inattendu.

--graph montre la structure des groupes :

ansible-inventory --graph

@all:
  |--@webservers:
  |  |--web1.lab
  |  |--web2.lab
  |--@dbservers:
  |  |--db1.lab

Pratiquer dans le lab

Cette page a un lab d’accompagnement : labs/inventaires/group-vars-host-vars/ dans stephrobert/ansible-training. Il définit app_port aux 3 niveaux (all, webservers, host_vars/web1.lab) et démontre la résolution via un playbook qui pose un fichier marqueur sur chaque host.

cd ~/Projets/ansible-training/labs/inventaires/group-vars-host-vars/

cat README.md
ansible-inventory -i inventory/hosts.yml --host web1.lab | grep app_port
ansible-inventory -i inventory/hosts.yml --host db1.lab | grep app_port
pytest -v challenge/tests/

Pièges courants

Symptôme	Cause	Fix
Variable absente alors qu’elle est dans `group_vars/X.yml`	Le dossier `group_vars/` est à côté du playbook au lieu de l’inventaire	Déplacer à côté de `inventory/hosts.yml`
Variable dans `host_vars/web1.yml` ignorée	Le hostname ne correspond pas au fichier	Doit être `host_vars/web1.lab.yml` si l’inventaire référence `web1.lab`
Override inattendu	Ne pas confondre niveaux : `group_vars/<sous-groupe>` > `group_vars/<parent>`	Tester avec `ansible-inventory --host`
Secret en clair lu par accident	Pas séparé dans `vault.yml`	Convention : `main.yml` + `vault.yml` (chiffré)
Comportement aléatoire entre 2 fichiers du dossier	Variable redéfinie dans 2 fichiers du même groupe	Une variable, un seul fichier — sinon ordre non garanti

À retenir

group_vars/ et host_vars/ sont placés à côté de l’inventaire (pas du playbook).
group_vars/all.yml s’applique à tous les hôtes — fallback par défaut.
group_vars/<groupe>.yml s’applique aux hôtes du groupe ; host_vars/<host>.yml ne s’applique qu’à un host.
Précédence : host_vars > group_vars/<groupe> > group_vars/all. Le plus local gagne.
Pattern dossier : group_vars/<groupe>/main.yml + vault.yml pour des configs volumineuses.
ansible-inventory --host <host> est l’outil pour vérifier la résolution.

Prochaines étapes

Inventaires multiples Gérer dev/staging/prod avec plusieurs inventaires et fusion automatique

Patterns d'hôtes Cibler exactement les hôtes voulus avec --limit et les opérateurs (:, &, !)

Vérifier un inventaire ansible-inventory --graph, --list, --host pour debugger les variables résolues

Précédence des variables (22 niveaux) Le tableau complet de la précédence officielle — objectif RHCE explicite