Dependencies and the roles you did not ask for · Ansible

Lesson 2 argued that a role which assumes a sibling ran first has an unstated dependency. meta/main.yml is the mechanism for stating it:

# roles/beta/meta/main.yml
dependencies:
  - role: gamma

Ansible always executes roles listed in dependencies before the role that lists them. That is the useful half. The other half is that this happens invisibly from the playbook — a play listing one role can run four, in an order the file does not show.

Ordering, executed

A play that lists beta and nothing else, where beta depends on gamma:

- name: roles keyword with a meta dependency
  hosts: web
  gather_facts: false
  roles:
    - role: beta
      tags: [deploy]
  tasks:
    - name: a play task
      ansible.builtin.debug:
        msg: play-task

Read-only / Safethe dependency runs first, and inherits the tags— Executed against ansible-core 2.21.3. gamma was never mentioned in the playbook. It runs before beta, and it carries the deploy tag applied to beta.

$ ansible-playbook -i inventory.ini rolesdep.yml --list-tasks

playbook: rolesdep.yml

play #1 (web): roles keyword with a meta dependency	TAGS: []
  tasks:
    gamma : gamma task one	TAGS: [deploy]
    beta : beta task one	TAGS: [deploy]
    a play task	TAGS: []

Two facts, both consequential:

gamma runs before beta. Dependencies are prerequisites, so this is the intended semantic and it is the reason to use the feature.
gamma inherited beta’s tag. --tags deploy now runs a role the operator did not know was in scope. Tag inheritance flows through the dependency chain exactly as it flows through a static import.

Dependencies are transitive. A role that depends on a role that depends on two more produces a chain the play never mentions, and the only way to see it is --list-tasks — which brings its own caveat, below.

Blast radius: what the play says is not what the play runs

The operator reviewing a change reads the playbook. If the playbook says roles: [beta] and the run touches four roles’ worth of configuration, the review examined a third of the change.

Before any run that matters, expand it:

ansible-playbook -i inventory/production.ini site.yml --list-tasks

Read the role prefixes. Every distinct prefix is a role that will execute against your hosts. If there are prefixes you did not expect, stop and find out why before the run rather than during it.

Deduplication, and where the dry run lies

A role listed twice in the same play normally runs once. That rule has three exceptions, and one of them is not what people expect.

A role reached through two dependency paths runs once

Two roles, dep1 and dep2, both declaring gamma as a dependency:

Read-only / Safewhat the parser reports— Executed. --list-tasks shows gamma twice - once for each role that depends on it.

$ ansible-playbook -i inventory.ini deps.yml --list-tasks

playbook: deps.yml

play #1 (local): local	TAGS: []
  tasks:
    gamma : gamma task one	TAGS: []
    dep1 : dep1 body	TAGS: []
    gamma : gamma task one	TAGS: []
    dep2 : dep2 body	TAGS: []

Read-only / Safewhat actually runs— Executed, same playbook, same inventory. gamma runs once. The second occurrence is deduplicated at run time and never appears.

$ ansible-playbook -i inventory.ini deps.yml

TASK [gamma : gamma task one] **************************************************
TASK [dep1 : dep1 body] ********************************************************
TASK [dep2 : dep2 body] ********************************************************

PLAY RECAP *********************************************************************
localhost                  : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

--list-tasks over-reports duplicate roles. It shows the tree the parser built; deduplication happens when the run reaches the second copy. Lesson 5 established that the dry run under-reports dynamic includes. This is the same tool erring in the opposite direction for a different reason, and both are worth knowing before you use --list-tasks output as evidence in a change review.

The same applies to a role written out twice by hand:

Read-only / Safelisted twice explicitly, runs once— Executed. The play lists gamma twice under roles:. --list-tasks shows two entries; the run produces one task and ok=1.

$ ansible-playbook -i inventory.ini dup.yml

TASK [gamma : gamma task one] **************************************************

PLAY RECAP *********************************************************************
localhost                  : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

It runs twice when the parameters differ

Read-only / Safesame role, different role parameters— Executed. The two invocations pass different values, so they are not duplicates and both run.

$ ansible-playbook -i inventory.ini dup3.yml

TASK [gamma : gamma task one] **************************************************
TASK [gamma : gamma task one] **************************************************

PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

roles:
  - role: gamma
    some_param: one
  - role: gamma
    some_param: two

This is the sane behaviour — a role parameterised two ways is doing two different jobs — and it is also how a dependency chain can execute a role several times without anybody intending it. Two roles that both depend on gamma but pass it different parameters get two runs of gamma, not one.

It runs twice when the role says so

Read-only / Safeallow_duplicates: true— Executed. roles/dupok/meta/main.yml sets allow_duplicates: true. The role is listed twice with identical parameters and runs twice.

$ ansible-playbook -i inventory.ini dup2.yml

TASK [dupok : dupok runs] ******************************************************
TASK [dupok : dupok runs] ******************************************************

PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

# roles/dupok/meta/main.yml
allow_duplicates: true

Set it when the role is genuinely an operation rather than a state — “deploy one instance of the app”, called once per instance. Leave it alone otherwise, because a role that describes a desired state has nothing to gain from converging twice and everything to lose if it is not idempotent.

When a dependency is the wrong tool

Dependencies are seductive because they make a role self-sufficient with one file. They have three costs that accumulate quietly.

The execution order stops being readable. A five-line play whose roles each carry two dependencies runs a tree. The playbook is no longer a description of what happens; --list-tasks is, and only approximately.

Variables flow in a direction people do not expect. A dependency is invoked from within the depending role’s context, so parameters passed to beta are not automatically passed to gamma. Values gamma needs must be set where gamma can see them, and “where gamma can see them” is a question about precedence rather than about the dependency graph.

Removing one is a breaking change to every consumer, and the breakage is of the quiet kind from lesson 2: a role that used to arrive with its prerequisites now arrives without them.

The alternative that costs less is usually explicit composition — list the roles in the play, in order, where a reader can see them:

- name: build the web tier
  hosts: web
  roles:
    - baseline
    - webapp
    - monitoring_agent

Three lines, one order, no hidden tree. Reserve meta/main.yml dependencies for the case they are genuinely good at: a role published for other people, whose prerequisites are an implementation detail its callers should not have to know.

Under the hood

Dependencies are resolved during role loading, at parse time, along with everything else static. The loader builds each role object, reads its meta/main.yml, and recursively loads the roles named there — which is why a dependency cycle is caught at parse time rather than looping forever, and why a dependency on a role that does not exist fails before any connection.

Deduplication happens later and by a different mechanism. Each role instance carries a hash of its name plus the parameters it was invoked with. As the play executes, a role whose hash has already been seen for this play is skipped, unless its meta/main.yml sets allow_duplicates: true.

Two consequences follow directly, and both are visible in the executed output above:

--list-tasks walks the parse-time tree, before any hash has been compared, so it shows every occurrence. The run compares hashes and shows fewer. Neither is wrong; they are answers to different questions.
Deduplication is per play, not per playbook. The same role in a second play of the same file runs again, because the seen-set is scoped to the play. This is the behaviour you want — a second play usually targets different hosts — and it surprises people who read “runs once” as a global guarantee.

What happens if two roles depend on the same role with different parameters?

It runs twice, in two different configurations, and the second run wins.

dep1 depends on gamma with gamma_mode: fast. dep2 depends on gamma with gamma_mode: safe. The parameters differ, so deduplication does not apply, so gamma executes once before each. The host ends up in whatever state the second invocation produced, and the first invocation’s work was either overwritten or, worse, partially overwritten.

The symptom is a host whose configuration matches neither role’s documentation, appearing only when both roles are in the same play. Run either alone and it is correct.

Finding it takes one command:

grep -rn --include=main.yml -A5 '^dependencies:' roles/*/meta/ | grep -c 'role: gamma'

The fix is not to make the parameters agree. It is to stop parameterising a shared dependency from two places — hoist gamma into the play, configure it once in the inventory, and remove it from both meta/main.yml files.