Vérifier un inventaire Ansible : ansible-inventory --graph, --list, --host

ansible-inventory est la commande de debug pour tout problème d’inventaire — variable manquante, groupe vide, host invisible, override inattendu. Elle lit l’inventaire comme Ansible le voit et expose le résultat dans plusieurs formats. Au RHCE, la maîtriser fait gagner des minutes précieuses face à un inventaire fourni.

Trois sous-commandes couvrent 95 % des cas : --graph (vue hiérarchique), --list (dump JSON complet), --host (variables résolues d’un seul host).

Pressé ? Les 3 commandes essentielles

# 1. Voir la hiérarchie des groupes (réflexe N°1 après chaque modif)
ansible-inventory --graph
# @all:
#   |--@webservers:
#   |  |--web1.lab
#   |  |--web2.lab
#   |--@dbservers:
#   |  |--db1.lab

# 2. Dump JSON complet (vérifier les variables au niveau groupe)
ansible-inventory --list

# 3. Variables résolues pour UN seul host (debug d'override)
ansible-inventory --host web1.lab
# {
#   "ansible_host": "10.10.20.21",
#   "ansible_user": "ansible",
#   "http_port": 80
# }

# Bonus : tester un pattern --limit avec --list-hosts
ansible all --list-hosts --limit "webservers:!web1.lab"

Sécurité non négociable :

• --graph après CHAQUE modification d’inventaire — détecte les fautes de frappe sur les noms de groupes (silencieuses sinon, le playbook tournera sur 0 host).
• --host <host> pour vérifier la valeur effective d’une variable après précédence — résout les surprises du genre « pourquoi http_port=8080 alors que je l’ai mis à 80 dans group_vars/all.yml ? ».
• Préférer ansible-inventory à un parsing manuel des fichiers d’inventaire — la commande prend en compte tous les niveaux (group_vars, host_vars, --extra-vars, plugins dynamiques) que la lecture du .yml brut ignore.

Ce que vous allez apprendre

• Voir la structure des groupes avec --graph.
• Dumper l’inventaire complet avec --list.
• Résoudre les variables d’un host précis avec --host.
• Exporter l’inventaire en YAML ou JSON pour migration.
• Identifier rapidement les erreurs d’inventaire.

--graph — la vue hiérarchique

ansible-inventory -i inventory/hosts.yml --graph

Sortie :

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

Ce qu’on lit : 3 groupes (control, dbservers, webservers) sous @all. Le groupe spécial @ungrouped liste les hôtes hors groupe — vide ici, normal. Les @ indiquent un groupe, sans @ un host.

Cas typique : vous attendez web3.lab mais il n’apparaît pas → inventaire mal écrit ou hostname mal orthographié.

--graph --vars — voir les variables des groupes

ansible-inventory -i inventory/hosts.yml --graph --vars

Sortie :

@all:
  |--@webservers:
  |  |--web1.lab
  |  |  |--{ansible_host = 10.10.20.21}
  |  |  |--{http_port = 9090}
  |  |--web2.lab
  |  |  |--{ansible_host = 10.10.20.22}
  |  |--{http_port = 8080}
  |--{ansible_user = ansible}

Avantage : voir les variables héritées par chaque niveau. http_port = 8080 apparaît au niveau du groupe webservers, mais 9090 au niveau de web1.lab (override host_vars).

--list — dump JSON complet

ansible-inventory -i inventory/hosts.yml --list

Sortie tronquée :

{
  "_meta": {
    "hostvars": {
      "web1.lab": {
        "ansible_host": "10.10.20.21",
        "ansible_user": "ansible",
        "http_port": 9090
      },
      "web2.lab": { ... },
      "db1.lab": { ... }
    }
  },
  "all": {
    "children": ["webservers", "dbservers", "control", "ungrouped"]
  },
  "webservers": {
    "hosts": ["web1.lab", "web2.lab"],
    "vars": {
      "http_port": 8080
    }
  }
}

Format machine-friendly : tous les hôtes, leurs variables résolues, et les groupes. C’est exactement le format qu’un script d’inventaire dynamique doit retourner — utile pour vérifier que votre script custom est conforme.

--list --yaml — dump YAML

ansible-inventory -i inventory/hosts.ini --list --yaml

Sortie :

all:
  children:
    webservers:
      hosts:
        web1.lab:
          ansible_host: 10.10.20.21
          http_port: 9090
        web2.lab:
          ansible_host: 10.10.20.22
          http_port: 8080
    dbservers:
      hosts:
        db1.lab:
          ansible_host: 10.10.20.31

Cas d’usage majeur : migration INI → YAML. Vous tapez --list --yaml sur l’ancien inventaire INI, copiez la sortie comme nouveau hosts.yml. Gain de temps important sur des inventaires complexes.

--host <host> — résolution d’un host précis

ansible-inventory -i inventory/hosts.yml --host web1.lab

Sortie :

{
  "ansible_host": "10.10.20.21",
  "ansible_user": "ansible",
  "ansible_python_interpreter": "/usr/bin/python3.12",
  "http_port": 9090,
  "worker_count": 4,
  "deploy_env": "production"
}

Ce qu’on voit : toutes les variables résolues pour web1.lab, peu importe leur source (group_vars/all, group_vars/webservers, host_vars/web1.lab, vars: dans hosts.yml). C’est l’outil n°1 pour debugger un override inattendu.

Pattern de debug — variable inattendue

Symptôme : votre playbook utilise app_port mais reçoit 80 au lieu de 9090 attendu.

Procédure :

# 1. Vérifier la structure de groupes
ansible-inventory -i inventory/hosts.yml --graph

# 2. Voir toutes les variables de l'hôte concerné
ansible-inventory -i inventory/hosts.yml --host web1.lab | grep app_port

# 3. Si elle est à 80 au lieu de 9090, c'est que host_vars n'est pas chargé
# → vérifier l'emplacement des fichiers
ls inventory/host_vars/    # doit contenir web1.lab.yml

# 4. Vérifier que l'extension est bonne
# host_vars/web1.lab → KO (sans .yml ignoré dans certains cas)
# host_vars/web1.lab.yml → OK

Règle d’or : les group_vars/ et host_vars/ doivent être à côté de l’inventaire, pas du playbook (sauf si l’inventaire est dans le même dossier).

--export — combiner avec d’autres outils

Pour piper l’inventaire vers jq :

# Lister tous les hostnames du groupe webservers
ansible-inventory -i inventory/hosts.yml --list \
  | jq -r '.webservers.hosts[]'

Sortie :

web1.lab
web2.lab

Pratique pour des scripts shell qui doivent boucler sur les hôtes hors d’Ansible — par exemple pour distribuer un fichier via rsync en parallèle.

Vérifier un inventaire dynamique

Sur un inventaire dynamique (plugin libvirt, AWS, NetBox), ansible-inventory --list montre ce que le plugin retourne :

ansible-inventory -i inventory/libvirt.yml --list

Si la sortie est vide ou ne contient pas l’hôte attendu :

1. Le plugin est-il activé dans ansible.cfg ?
2. Les credentials (clé API, certificat libvirt) sont-ils corrects ?
3. Le filtre du plugin est-il trop restrictif ?

C’est la commande qu’on lance après chaque modification d’un script d’inventaire dynamique pour s’assurer qu’il est toujours valide.

Format --toml (Ansible 2.18+)

ansible-inventory -i inventory/hosts.yml --list --toml

Sortie en TOML — utile si votre outillage en aval (config-as-code) lit du TOML. Rare mais bon à connaître.

Pièges courants

Symptôme	Cause	Fix
--host web1.lab retourne {} vide	Le host n’est pas dans l’inventaire	--graph pour vérifier l’orthographe
Variable absente dans --host mais présente dans host_vars/web1.yml	Mauvais nom de fichier (.yaml au lieu de .yml, ou path incorrect)	Vérifier ls inventory/host_vars/
--list --yaml plante	Vieille version d’Ansible	Mettre à jour ou utiliser --list (JSON)
--graph montre @ungrouped plein	Hôtes hors de tout groupe	Vérifier que les hôtes sont bien dans children
Lent sur grand inventaire	Dynamique avec appel API à chaque commande	Utiliser fact_caching pour les facts, et un cache plugin pour l’inventaire

Glissez pour voir

À retenir

• --graph : structure hiérarchique des groupes (vue rapide).
• --graph --vars : graph + variables par niveau.
• --list : dump JSON complet (machine-friendly, format scripts dynamiques).
• --list --yaml : version YAML — utile pour migrer INI vers YAML.
• --host <host> : variables résolues d’un seul host (debug n°1).
• Combinable avec jq ou yq pour des scripts shell.

Prochaines étapes

Patterns d'hôtes Une fois l'inventaire validé, cibler exactement les hôtes voulus avec --limit

Inventaires multiples -i inv1 -i inv2 — comment Ansible fusionne plusieurs sources

group_vars et host_vars Si --host montre une mauvaise valeur, c'est ici qu'il faut regarder

Inventaire dynamique pour KVM Quand l'inventaire est généré à la volée depuis libvirt, --list devient critique

×

📖 Voir la documentation →