Ansible inventory and playbook preflight cheat sheet
Check configuration, inventory groups, resolved host variables and selected playbook hosts before running automation.
ansible-core CLI on the control node. Use a trusted inventory and playbook; plugins, inventory scripts and lookups can execute code even during preflight.
Updated · Ansible · 6 min read
| Command | What it does |
|---|---|
ansible --version | Identify runtime and configuration file |
ansible-config dump --only-changed | Inspect effective nondefault configuration |
ansible-inventory -i inventory.ini --graph | Inspect inventory group membership |
ansible-inventory -i inventory.ini --host web01 | Inspect resolved inventory variables for one host |
ansible-playbook -i inventory.ini site.yml --list-hosts | List hosts selected by the playbook |
ansible-playbook -i inventory.ini site.yml --syntax-check | Check playbook syntax without running tasks |
Walkthrough
Replace inventory.ini, site.yml and web01 with local trusted inputs. These examples do not execute playbook tasks. Inventory output can include secrets; keep variable dumps private.
Step 1: Identify runtime and configuration file
ansible --version
Record ansible-core version, Python interpreter and the selected configuration file. A shell in another directory or virtual environment can load different settings; compare the actual paths with the automation runner before investigating hosts.
Step 2: Inspect effective nondefault configuration
ansible-config dump --only-changed
Review changed settings and their origin, especially inventory and collection paths. This is not the resolved set of every host variable. Redact credentials or sensitive paths before sharing the output outside the control-node team.
Step 3: Inspect inventory group membership
ansible-inventory -i inventory.ini --graph
Confirm that the intended host belongs to the group referenced by the playbook. A parse warning or an empty group points toward inventory selection or syntax. A valid graph does not prove that SSH access or task privileges will work.
Step 4: Inspect resolved inventory variables for one host
ansible-inventory -i inventory.ini --host web01
Compare ansible_host, connection type and group-derived variables with the intended target. The alias may differ from its DNS name. Treat the output as sensitive because inventory variables can contain passwords and tokens.
Step 5: List hosts selected by the playbook
ansible-playbook -i inventory.ini site.yml --list-hosts
Compare each play host pattern with the expected maintenance scope. This does not execute tasks or test connectivity. Additional limit flags in the real runner can narrow the selected set further, so compare the exact production command.
Step 6: Check playbook syntax without running tasks
ansible-playbook -i inventory.ini site.yml --syntax-check
Resolve reported YAML, task or collection-loading errors before execution. Passing syntax checks does not validate runtime variables, network access, task behavior or dynamically included content in every possible branch.
WORKED INCIDENT
Practical case: A playbook reports no hosts matched
Fictional teaching scenario; observations are examples, not captured production output.
Situation
An operator expects a web-server maintenance play to select web01, but the automation runner selects zero hosts.
Investigation sequence
1. Identify runtime and configuration file
ansible --versionRecord the config file and runtime used in the failing shell; compare them with the runner.
2. Inspect inventory group membership
ansible-inventory -i inventory.ini --graphInspect the inventory graph. In this example web01 belongs to webservers, while no web group exists.
3. List hosts selected by the playbook
ansible-playbook -i inventory.ini site.yml --list-hostsList playbook hosts with the same inventory. The fictional play targets web, producing an empty selection.
4. Check playbook syntax without running tasks
ansible-playbook -i inventory.ini site.yml --syntax-checkCheck syntax separately so a syntactically valid playbook is not confused with correct targeting.
Example findings
Illustrative findings: inventory has webservers/web01; the play targets web; syntax check passes; list-hosts returns zero targets.
Interpret the findings
The host-pattern mismatch explains the empty selection in this example. Syntax success does not prove that a play targets the intended equipment.
Verify the outcome
After the owner corrects the approved inventory or play pattern, repeat the graph and list-hosts checks with the runner exact arguments. Review the selected hosts before scheduling execution.
Escalation handoff
Send the configuration path, inventory path, group names and selected host count to the automation owner. Share variable names rather than secret values.