Stage 4 · Provision

Roles & Collections

Role Dependencies & Reuse

meta/main.yml, include_role, and import_role patterns.

6 min readAnsible AutomationProvision

Declaring Dependencies

Role dependencies are declared in meta/main.yml. Ansible automatically includes dependent roles before the role that depends on them. Dependencies can have their own dependencies, forming a tree.

roles/app/meta/main.yml


---
galaxy_info:
  author: Your Name
  description: Application deployment role
  license: MIT
  min_ansible_version: "2.14"

dependencies:
  - role: common
  - role: nginx
    vars:
      nginx_port: 8080
  - role: monitoring
    when: enable_monitoring | default(true)

Dependencies run in order before the main role tasks. They inherit variables passed via vars.

include_role vs import_role

Feature	include_role	import_role
When processed	Runtime (dynamic)	Parse time (static)
Tags	Inherited from include	Applied to all tasks
Conditionals	Supports when	Does not support when
Loops	Can use loop	Cannot use loop
Performance	Slightly slower	Faster

Dynamic inclusion with include_role


- name: Deploy application
  include_role:
    name: app
  vars:
    app_version: "{{ version }}"
  when: deploy_app | default(true)

include_role processes at runtime, so when conditionals work. Use it when role inclusion depends on runtime facts.

Static inclusion with import_role


- name: Import common setup
  import_role:
    name: common
  tags: [setup, common]

import_role processes at parse time. Tags applied to import_role propagate to all tasks in the role.

Dependency Ordering

Dependencies execute before the dependent role's tasks. Within a role, tasks run in the order defined in main.yml. Across roles, dependencies form a tree that Ansible flattens and executes in order.

Execution order example


# Role A depends on Role B
# Role B depends on Role C

# Execution order:
# 1. Role C tasks (dependency of B)
# 2. Role B tasks (dependency of A)
# 3. Role A tasks

roles:
  - role: app        # Runs last
  # app/meta/main.yml:
  #   dependencies:
  #     - role: nginx  # Runs second
  #     # nginx/meta/main.yml:
  #     #   dependencies:
  #     #     - role: common  # Runs first

Ansible flattens the dependency tree and executes roles in dependency order. No role runs until all its dependencies complete.

Conditional Role Inclusion

Conditional roles


roles:
  - role: common
  - role: nginx
    when: install_nginx | default(true)
  - role: postgresql
    when: "'dbservers' in group_names"
  - role: monitoring
    vars:
      alert_email: ops@example.com
    when: environment == "production"

when conditions on roles let you include roles only for specific hosts, groups, or environments.

Avoiding Circular Dependencies

Circular dependency errors

If Role A depends on Role B and Role B depends on Role A, Ansible throws an error. Always verify dependency chains are acyclic. Use ansible-galaxy info role_name to inspect dependencies.

Keep dependencies minimal

Every dependency adds complexity and execution time. Only declare dependencies that are truly required. Avoid dependency chains deeper than 3 levels.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.