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.
1. The "Who Wins?" Dilemma
Consider a scenario common to multi-environment fleets:
- You set
app_port: 8080in playbook defaultvars:. - Your inventory group variables override it to
app_port: 3000. - A shared Variable Set attached to your project sets
app_port: 5000. - Right before deployment, you pass
app_port: 9000in 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):
[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:
- Extra Variables (
extra_vars) always win: Anything passed in the Extra Variables editor (or via webhookextra_variables) is injected as runtime extra-vars toansible-runner. It overrides all playbook, inventory, and role variables. - Job-selected Variable Sets override Playbook defaults: If a variable set attached at run-time specifies
nginx_workers: 8, it supersedes the playbook defaultnginx_workers: 4. - Explicit Host Overrides beat Group Defaults: Host-level variables (e.g.
ciel_port: 2222set 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 roledefaults/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_variablesstrictly for runtime deployment triggers, such asrelease_tag: "v1.4.2"ordry_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):
- Command line values (e.g.
-u my_user, connection flags, not true variables) - Role defaults (
role/defaults/main.yml, intended for easily overridden fallbacks) - Inventory file or script group vars
- Inventory
group_vars/all - Playbook
group_vars/all - Inventory
group_vars/* - Playbook
group_vars/* - Inventory file or script host vars
- Inventory
host_vars/* - Playbook
host_vars/* - Host facts / cached
set_facts(discovered facts fromansible.builtin.setup) - Play
vars(declared at play root) - Play
vars_prompt(interactive CLI prompt values) - Play
vars_files(external files loaded at play root) - Role vars (
role/vars/main.yml, intended to be strictly internal to the role) - Block vars (variables declared on a task block)
- Task vars (variables declared directly on a task)
include_vars(dynamically loaded variables during execution)set_facts/ registered vars (register: result)- Role (and
include_role) params (parameters passed to a role invocation) - Include params (parameters passed to an
include_tasksorimport_tasks) - 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 playbookvars:(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.