Role Dependencies

Analogy categoryAnalogies

Declaring Dependencies in meta/main.yml

A role can declare that it depends on other roles by listing them under the dependencies key inside meta/main.yml. When Ansible processes a play, it resolves these dependencies first, executing each dependent role's tasks before the depending role's own tasks run, which lets you express prerequisites like 'the app role requires the common role's baseline packages and firewall rules to already be applied.' Dependencies can also pass variables specific to that invocation, so the same dependency role can be reused with different parameters by different parents.

🏏

Cricket analogy: It's like a fast bowler needing a warmed-up physio clearance and a properly rolled pitch inspection before the umpire allows the over to start — prerequisite steps that must complete first.

yaml

# roles/app/meta/main.yml
dependencies:
  - role: common
    vars:
      common_timezone: "UTC"
  - role: firewall
    vars:
      firewall_allowed_ports: [80, 443]

Ordering and Automatic Deduplication

When multiple roles in the same play declare the same dependency, Ansible by default runs that shared dependency only once per play, tracked by role name and the exact parameters passed, to avoid redundant work like installing the same base package twice. This deduplication can be disabled per-role with allow_duplicates: true in the dependent role's meta/main.yml, which is occasionally needed for roles designed to be applied multiple times with different variables, such as a generic 'create_user' role invoked once per user account.

🏏

Cricket analogy: It's like the ground staff rolling the pitch only once before play starts even though both team managers separately requested it — the shared preparation step happens a single time, not once per requester.

Deduplication is keyed on role name plus the exact set of parameters passed; if two dependency declarations pass different vars, Ansible treats them as distinct invocations and runs the role twice.

Dependencies vs. Explicit Ordering with roles:

meta/main.yml dependencies express implicit, structural prerequisites that a role cannot function without, whereas listing multiple roles explicitly under a play's roles: key expresses an ordering the playbook author controls directly. The tradeoff is discoverability versus coupling: meta dependencies guarantee correctness even if someone forgets to order roles properly in a playbook, but they also hide coupling inside the role itself, which can surprise consumers who expect a role to be standalone. Many teams intentionally avoid meta dependencies for anything beyond tightly coupled internal roles, preferring to make prerequisites explicit in the playbook instead.

🏏

Cricket analogy: It's like a fielding restriction hard-coded into the powerplay rules (an implicit dependency of the format) versus a captain's own explicit field placement decision that they choose fresh each over.

Overusing meta dependencies for loosely related roles creates hidden coupling that makes roles harder to reuse independently; reserve them for prerequisites the role truly cannot function without.

meta/main.yml's dependencies key lists roles that must run before the current role, resolved automatically by Ansible.
Dependent roles can receive their own vars, letting the same dependency role be reused with different parameters.
Ansible deduplicates identical dependency invocations (same role + same params) once per play by default.
allow_duplicates: true opts a role out of deduplication when it's designed to run multiple times.
meta dependencies express implicit prerequisites; roles: in a playbook expresses explicit, author-controlled ordering.
Overusing meta dependencies increases coupling and reduces a role's standalone reusability.
Prefer explicit playbook-level ordering for loosely related roles, and reserve meta dependencies for tightly coupled internal roles.