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

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

Les quatre premières lignes décrivent le même moment, celui où la commande de vérification contredit ce que vous croyiez avoir écrit : c'est elle qui a raison, puisqu'elle montre l'inventaire tel qu'Ansible le voit. La dernière sort du diagnostic et touche à la performance, le cache des faits et celui de l'inventaire répondant à deux problèmes distincts.

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

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

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

Pour aller plus loin

• Concepts des plugins : comprendre ce que -vvv raconte quand un plugin d'inventaire ne rend rien.
• Plugin libvirt (KVM) : un premier inventaire dynamique à inspecter avec les commandes vues ici.
• Écrire un script custom : le format JSON attendu, celui que --list vous sert justement à valider.

×

📖 Voir la documentation →