Ansible Variables Deep Dive: From Inventory to Extra-Vars, Facts, and Debugging

I once spent a weekend debugging why a playbook deployed the wrong version of an application to production. The symptom was subtle: the app version was correct on 9 out of 10 servers, but one server got an older build. After hours of grepping logs and scratching my head, I discovered the root cause: a variable defined in the inventory file for that specific host was being overridden by a role default variable with a lower priority than I assumed. The variable precedence ladder is not always intuitive, and a single misplaced variable can cause silent failures.

Historically, Ansible started with simple inventory variables and expanded to support complex automation needs. The variable system grew organically: playbook vars, role vars, include_vars, vars_prompt, and extra-vars. Facts were introduced to provide system introspection, but they come at a performance cost. The community has learned hard lessons about variable scoping, precedence, and debugging.

This article covers all variable types: inventory, playbook, role (defaults and vars), and extra-vars. You'll learn how to use register to capture task output, set_fact to create derived variables, the hostvars magic variable for cross-host data, and the ansible_facts dictionary for system facts. We'll explore the trade-offs of gather_facts: false and how to use the debug module effectively. Real production incidents and debugging patterns are included throughout.

1. Variable Types: Where to Define Them

Ansible variables can be defined in multiple places, each with a specific precedence. From lowest to highest: 1. Inventory variables: host_vars, group_vars (e.g., group_vars/all.yml, host_vars/web1.yml). 2. Playbook variables: vars: block in a play or vars_files:. 3. Role defaults: roles/role_name/defaults/main.yml — lowest precedence within a role. 4. Role vars: roles/role_name/vars/main.yml — higher precedence than defaults. 5. Block and task variables: vars: within a block or task. 6. set_fact / register: Dynamic variables created during execution. 7. Extra-vars: -e 'key=value' or --extra-vars @file.json — highest precedence.

Production pattern: Use inventory variables for environment-specific values, role defaults for sane defaults, and extra-vars only for emergency overrides. Avoid defining the same variable in multiple places; it leads to confusion.

Code example: ``yaml # inventory/group_vars/all.yml app_port: 8080 app_user: deploy ` `yaml # playbook.yml - hosts: webservers vars: app_port: 9090 # overrides inventory roles: - role: app ` `yaml # roles/app/defaults/main.yml app_port: 3000 # lowest priority app_user: root ``

To see the resolved value, use: ``bash ansible web1 -m debug -a 'var=app_port' -i inventory ``

Gotcha: Role defaults are often overridden unintentionally. Always check with --check and --diff.

2. Inventory Variables: host_vars and group_vars

Inventory variables are defined in the inventory directory structure. Common patterns: - group_vars/all.yml: variables for all hosts. - group_vars/webservers.yml: variables for the webservers group. - host_vars/web1.yml: variables specific to host web1.

Directory structure: `` inventory/ production/ hosts.yml group_vars/ all.yml webservers.yml host_vars/ web1.yml ``

Precedence within inventory: host_vars > group_vars (child groups can inherit from parent groups, but more specific group wins).

Production tip: Use ansible-inventory --list --yaml to dump all inventory variables for debugging. Example: ``bash ansible-inventory -i inventory/production --list --yaml ``

Code example: ``yaml # group_vars/webservers.yml http_port: 80 server_name: example.com ` `yaml # host_vars/web1.yml http_port: 8080 # overrides group_vars ``

Gotcha: If you use dynamic inventory scripts, ensure they output variables correctly. Test with ansible-inventory before running playbooks.

3. Playbook Variables: vars, vars_files, and vars_prompt

Playbook variables are defined directly in the playbook file. They have higher precedence than inventory but lower than role vars.

vars block: ``yaml - hosts: all vars: package: nginx state: present tasks: - name: Install package apt: name: "{{ package }}" state: "{{ state }}" ``

vars_files: Load variables from external files. ``yaml - hosts: all vars_files: - vars/common.yml - "vars/{{ ansible_os_family }}.yml" ``

vars_prompt: Interactive input (avoid in automation). ``yaml - hosts: all vars_prompt: - name: "db_password" prompt: "Enter database password" private: yes ``

Production pattern: Use vars_files to separate sensitive data (encrypted with ansible-vault) from playbook logic. Example: ``bash ansible-vault create vars/secrets.yml ` Then in playbook: `yaml vars_files: - vars/secrets.yml ``

Gotcha: vars_prompt is not idempotent and breaks automation. Never use it in CI/CD pipelines.

Debug: Print all playbook variables with: ``yaml - debug: var: vars ``

4. Role Variables: defaults vs. vars

Roles can define variables in two locations: defaults/main.yml (lowest precedence) and vars/main.yml (higher precedence). The difference is crucial for role reusability.

Precedence order: role defaults < inventory < playbook vars < role vars < set_fact < extra-vars.

Production pattern: Use defaults/main.yml for configurable settings, vars/main.yml for internal constants. Document which variables are overridable.

Code example: ``yaml # playbook.yml - hosts: all vars: nginx_port: 8080 # overrides role defaults, but not role vars roles: - nginx ``

Gotcha: If you define a variable in both defaults and vars with the same name, vars wins. Avoid duplication.

5. Extra-Vars: The Emergency Override

Extra-vars (-e or --extra-vars) have the highest precedence of all variable sources. They can be passed as key=value pairs, JSON, or YAML files.

Syntax: ``bash ansible-playbook playbook.yml -e 'myvar=value' ansible-playbook playbook.yml -e '@vars.json' ansible-playbook playbook.yml -e "{'myvar':'value'}" ``

Production caution: Extra-vars can override anything, including role vars. They bypass normal precedence. Use them sparingly and audit with --syntax-check.

Code example: ``bash # Override app version in deployment ansible-playbook deploy.yml -e 'app_version=v2.1.3' -i production ``

Debug: To see all extra-vars: ``bash ansible-playbook playbook.yml -e 'debug_extra=true' --syntax-check ` Add a task: `yaml - debug: var: extra_vars | default({}) ``

Gotcha: Extra-vars from files are merged; if the same key exists in multiple files, the last one wins. Order matters: -e @a.yml -e @b.yml — b overrides a.

6. The register Keyword: Capturing Task Output

The register keyword captures the output of a task into a variable. It stores a dictionary with keys: changed, failed, rc, stdout, stderr, etc.

Basic usage: ```yaml - name: Check if file exists stat: path: /etc/app.conf register: file_stat

• name: Print file existence
• debug:
• msg: "File exists: {{ file_stat.stat.exists }}"
• ```

Common patterns: ```yaml - name: Run a command command: /usr/bin/uptime register: uptime_output

• name: Show uptime
• debug:
• var: uptime_output.stdout
• ```

Conditional execution based on register: ``yaml - name: Restart service if config changed service: name: nginx state: restarted when: config_update.changed ``

Gotcha: register only captures the task's result; if the task is skipped, the variable is undefined. Use | default({}) to avoid errors.

Production pattern: Always check result.failed or result.rc when using command or shell modules.

7. The set_fact Module: Creating Dynamic Variables

set_fact creates or updates variables during playbook execution. Unlike register, it can assign arbitrary values, not just task results.

Basic usage: ``yaml - name: Set a fact set_fact: my_custom_var: "{{ some_other_var | upper }}" ``

Example: ```yaml - name: Get instance ID uri: url: http://169.254.169.254/latest/meta-data/instance-id return_content: yes register: instance_id_result

• name: Set instance ID fact
• set_fact:
• instance_id: "{{ instance_id_result.content }}"
• ```

Cross-host facts: set_fact creates a host-level variable. To share across hosts, use hostvars.

Gotcha: set_fact variables are only available for the current host and current playbook run. They are not persistent.

Production pattern: Use set_fact to compute derived values early in the playbook to avoid repeated lookups.

8. The hostvars Magic Variable: Cross-Host Communication

hostvars is a dictionary containing all variables for all hosts in the inventory. It allows a play to access facts or variables from other hosts.

Syntax: ``yaml {{ hostvars['target_host']['variable_name'] }} ``

Common use case: Get IP address of a database server from an application server play. ``yaml - name: Print database IP debug: msg: "DB IP is {{ hostvars['db1']['ansible_default_ipv4']['address'] }}" ``

Production pattern: Use hostvars to build dynamic inventories or configuration files.

Code example: ``yaml - name: Generate haproxy config template: src: haproxy.cfg.j2 dest: /etc/haproxy/haproxy.cfg vars: backend_servers: "{{ groups['webservers'] | map('extract', hostvars, ['ansible_default_ipv4', 'address']) | list }}" ``

Gotcha: If the target host hasn't been processed yet (e.g., different play), hostvars will be empty. Use serial or order to control execution order.

9. Gathered Facts (ansible_facts): System Introspection

Facts are system information automatically gathered by Ansible when gather_facts: true (default). They are stored in the ansible_facts dictionary and can be accessed directly as variables (e.g., ansible_os_family, ansible_default_ipv4.address).

Accessing facts: ``yaml - debug: msg: "OS is {{ ansible_os_family }} {{ ansible_distribution_version }}" ``

Custom facts: Place scripts or static files in /etc/ansible/facts.d/ on target hosts. They are gathered as ansible_local.

Example custom fact: ``bash # /etc/ansible/facts.d/role.fact [general] role = webserver datacenter = us-east ` Accessed as {{ ansible_local['role']['general']['role'] }}`.

Gotcha: Fact gathering adds ~10 seconds per host. For large environments, this is significant.

10. gather_facts: false: Performance vs. Convenience

Setting `gather_facts: false at the play level skips the setup` module invocation, significantly reducing playbook runtime. However, you lose access to system facts.

Syntax: ``yaml - hosts: all gather_facts: false tasks: - name: Install package apt: name: nginx state: present ``

Performance gain: On a 100-host environment, disabling facts can cut runtime from 10 minutes to 2 minutes.

Trade-off: You cannot use ansible_os_family or other facts. If you need a specific fact, use the setup module selectively: ``yaml - name: Gather minimal facts setup: filter: ansible_os_family when: ansible_os_family is not defined ``

Production pattern: Use gather_facts: false in most plays, and explicitly call setup: with filter: for required facts. Cache facts with fact_caching.

Gotcha: If you disable facts and then try to use a fact variable, you'll get an undefined variable error. Use | default('') or conditional checks.

11. The debug Module: Inspecting Variables in Flight

The debug module is your best friend for variable inspection. It can print messages, variable values, or verbosity-dependent output.

Verbosity control: ``yaml - debug: msg: "This only shows with -v" verbosity: 1 ``

Production pattern: Add debug tasks with verbosity: 2 to avoid cluttering normal output. Use --verbose or -v to see them.

Code example: ```yaml - name: Print all facts debug: var: ansible_facts verbosity: 2

• name: Print specific variable
• debug:
• var: my_custom_var
• ```

Gotcha: debug: var=myvar prints the variable name and value. If the variable is undefined, it prints the string "VARIABLE IS NOT DEFINED!".

12. Putting It All Together: A Production Debugging Workflow

When a variable-related issue arises in production, follow this systematic workflow:

1. Reproduce with verbosity: Run the playbook with -vvv to see variable resolution.
2. ```bash
3. ansible-playbook playbook.yml -i inventory -vvv | grep 'variable'
4. ```
5. Dump all variables: Use a debug task to dump hostvars.
6. ```yaml
7. - name: Dump host variables
8. debug:
9. var: hostvars[inventory_hostname]
10. tags: [never, debug]
11. ```
12. Check precedence: Use ansible-inventory to see inventory variables.
13. ```bash
14. ansible-inventory -i inventory --list --yaml
15. ```
16. Test with extra-vars: Override the suspect variable to see if it changes behavior.
17. ```bash
18. ansible-playbook playbook.yml -e 'suspect_var=test_value'
19. ```
20. Use --syntax-check: Validates variable references.
21. ```bash
22. ansible-playbook playbook.yml --syntax-check
23. ```
24. Check fact cache: If using caching, clear it.
25. ```bash
26. ansible-playbook playbook.yml --flush-cache
27. ```
28. Isolate the issue: Create a minimal playbook that only prints the variable.
29. ```yaml
30. - hosts: target_host
31. gather_facts: false
32. tasks:
33. - debug:
34. var: suspect_var
35. ```

Real incident: We had a variable app_version that was undefined in production. Following the workflow, we discovered that the fact cache was stale (contained an old version). Flushing the cache and re-gathering facts resolved it.