Variables & Precedence•6 min read•Important

Variable Precedence & Overrides

Demystify Ansible's 22 variable precedence levels with CIEL's predictable resolution hierarchy, ordered variable sets, and runtime overrides.

If you have ever spent two hours debugging an Ansible run wondering why db_port: 5432 was completely ignored, only to discover a default variable buried inside a legacy role from three years ago silently took precedence, you already know the pain.

Ansible officially has 22 levels of variable precedence. Yes, twenty-two.

In CIEL, we cannot rewrite Ansible's internal engine rules, but we can eliminate the guessing game. CIEL structures variable resolution into a predictable, visible pipeline so you always know exactly which value wins before you hit execute.

Run Playbook Custom Options with Variable Precedence Popover and AST Inspector

1. The "Who Wins?" Dilemma

Consider a scenario common to multi-environment fleets:

  1. You set app_port: 8080 in playbook default vars:.
  2. Your inventory group variables override it to app_port: 3000.
  3. A shared Variable Set attached to your project sets app_port: 5000.
  4. Right before deployment, you pass app_port: 9000 in the Extra Variables drawer.

Which port actually gets deployed to your server?

Without clear precedence rules, your rollout is a coin toss. In CIEL, the hierarchy is deterministic: 9000 wins every single time.


2. The CIEL Resolution Hierarchy

CIEL evaluates and merges configuration values across five clear layers, ranked from lowest priority (base fallbacks) to highest priority (absolute winners):

text
[LOWEST PRECEDENCE - Base Fallbacks]
  1. Group Variables
     Inventory group variables (group_vars) shared across hosts in an inventory.

  2. Host Variables
     Per-host entity variables set on individual servers. Overrides group variables.

  3. Playbook Defaults
     Default variables declared in Playbook YAML (vars: blocks) or Role defaults.

  4. Assigned Variable Sets (Ordered #1 -> #N)
     Applied sequentially in selector order. Later sets in the list override earlier ones.

  5. Extra Variables (Winner)
     Direct runtime variables configured in the job run form, webhook payloads, or schedules.
[HIGHEST PRECEDENCE - The Undisputed Winner]

The Three Golden Rules:

  1. Extra Variables (extra_vars) always win: Anything passed in the Extra Variables editor (or via webhook extra_variables) is injected as runtime extra-vars to ansible-runner. It overrides all playbook, inventory, and role variables.
  2. Job-selected Variable Sets override Playbook defaults: If a variable set attached at run-time specifies nginx_workers: 8, it supersedes the playbook default nginx_workers: 4.
  3. Explicit Host Overrides beat Group Defaults: Host-level variables (e.g. ciel_port: 2222 set on a specific host) override inventory-wide defaults for that single machine.

3. Variable Set Ordering & Conflicts

When you attach multiple Variable Sets to a single run, what happens if Set A defines log_level: info and Set B defines log_level: debug?

  • Sequential Evaluation: Variable sets are processed from top to bottom (#1 -> #N).
  • Last-Write-Wins: If both sets define the same key, the later set in the list wins.
  • Visual Ordering: In the Run Playbook drawer, the ordered selector lets you inspect, reorder, or remove sets so the merge sequence matches your operational intent.

4. Inspecting Variables Before Execution

CIEL provides multiple inspection points so you never have to deploy blind:

  • Variable Set Preview: Click the eye icon next to any attached variable set to inspect its parsed table view or raw YAML.
  • Inventory YAML Preview: In the target inventory's YAML Preview & Settings tab, click Render to view the compiled Ansible inventory projection with all host and group variables resolved.
  • Precedence Guide Tooltip: Click the Variable Precedence badge in the Run Playbook drawer for an instant reminder of the resolution ladder.

5. Practical Rules for Sanity

  • Put Safe Fallbacks in Defaults: Keep baseline values in playbook vars: or role defaults/main.yml. Never hardcode production IP addresses or secrets in playbook files.
  • Put Environment Config in Variable Sets: Maintain dedicated Variable Sets for environment-specific infrastructure (such as db-prod, db-staging, internal-dns).
  • Reserve Extra Variables for Ephemeral Parameters: Keep extra_variables strictly for runtime deployment triggers, such as release_tag: "v1.4.2" or dry_run: true.

6. Complete Reference: The 22 Ansible Precedence Levels

For deeper upstream troubleshooting, the list below reflects the official hierarchy defined in the Ansible Playbook Variables Documentation. It details Ansible's complete internal precedence from lowest priority (1) to absolute winner (22):

  1. Command line values (e.g. -u my_user, connection flags, not true variables)
  2. Role defaults (role/defaults/main.yml, intended for easily overridden fallbacks)
  3. Inventory file or script group vars
  4. Inventory group_vars/all
  5. Playbook group_vars/all
  6. Inventory group_vars/*
  7. Playbook group_vars/*
  8. Inventory file or script host vars
  9. Inventory host_vars/*
  10. Playbook host_vars/*
  11. Host facts / cached set_facts (discovered facts from ansible.builtin.setup)
  12. Play vars (declared at play root)
  13. Play vars_prompt (interactive CLI prompt values)
  14. Play vars_files (external files loaded at play root)
  15. Role vars (role/vars/main.yml, intended to be strictly internal to the role)
  16. Block vars (variables declared on a task block)
  17. Task vars (variables declared directly on a task)
  18. include_vars (dynamically loaded variables during execution)
  19. set_facts / registered vars (register: result)
  20. Role (and include_role) params (parameters passed to a role invocation)
  21. Include params (parameters passed to an include_tasks or import_tasks)
  22. Extra vars (-e "key=value", injected via CIEL's Extra Variables editor or runner extravars file; overrides all prior levels)

The Classic Debugging Trap: Level 2 vs. Level 15

The single most frequent source of variable confusion in Ansible is the difference between:

  • role/defaults/main.yml (Level 2): Designed for defaults that users can easily override from inventories or playbooks.
  • role/vars/main.yml (Level 15): Designed for internal constants that should not change. Because it sits at Level 15, it silently ignores playbook vars: (Level 12) and inventory variables (Levels 3-10).

When you pass variables in CIEL's Extra Variables editor, CIEL feeds them directly at Level 22, guaranteeing that your intended override wins regardless of how upstream roles were structured.

Reference: For full upstream details on scoping rules and dictionary merges, consult the official Ansible Variable Precedence Guide.