include_role¶

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 2.2.

Synopsis¶

Dynamically loads and executes a specified role as a task.
May be used only where Ansible tasks are allowed - inside C(pre_tasks), C(tasks), or C(post_tasks) play objects, or as a task inside a role.
Task-level keywords, loops, and conditionals apply only to the C(include_role) statement itself.
To apply keywords to the tasks within the role, pass them using the O(apply) option or use M(ansible.builtin.import_role) instead.
Ignores some keywords, like C(until) and C(retries).
This module is also supported for Windows targets.
Does not work in handlers.

Parameters¶

Parameter	Defaults / Choices	Comments
allow_duplicates bool	Default: True	Overrides the role's metadata setting to allow using a role more than once with the same parameters.
apply		Accepts a hash of task keywords (for example C(tags), C(become)) that will be applied to all tasks within the included role. Version Added: 2.7
defaults_from str	Default: main	File to load from a role's C(defaults/) directory.
handlers_from str	Default: main	File to load from a role's C(handlers/) directory. Version Added: 2.8
name str required		The name of the role to be executed.
public bool		This option dictates whether the role's C(vars) and C(defaults) are exposed to the play. If set to V(true) the variables will be available to tasks following the C(include_role) task. This functionality differs from standard variable exposure for roles listed under the C(roles) header or M(ansible.builtin.import_role) as they are exposed to the play at playbook parsing time, and available to earlier roles and tasks as well. Version Added: 2.7
rolespec_validate bool	Default: True	Perform role argument spec validation if an argument spec is defined. Version Added: 2.11
tasks_from str	Default: main	File to load from a role's C(tasks/) directory.
vars_from str	Default: main	File to load from a role's C(vars/) directory.

Notes¶

Note

Handlers and are made available to the whole play.
After Ansible 2.4, you can use M(ansible.builtin.import_role) for B(static) behaviour and this action for B(dynamic) one.

Examples¶

- ansible.builtin.include_role:
    name: myrole

- name: Run tasks/other.yaml instead of 'main'
  ansible.builtin.include_role:
    name: myrole
    tasks_from: other

- name: Pass variables to role
  ansible.builtin.include_role:
    name: myrole
  vars:
    rolevar1: value from task

- name: Use role in loop
  ansible.builtin.include_role:
    name: '{{ roleinputvar }}'
  loop:
    - '{{ roleinput1 }}'
    - '{{ roleinput2 }}'
  loop_control:
    loop_var: roleinputvar

- name: Conditional role
  ansible.builtin.include_role:
    name: myrole
  when: not idontwanttorun

- name: Apply tags to tasks within included file
  ansible.builtin.include_role:
    name: install
    apply:
      tags:
        - install
  tags:
    - always

Authors¶

Ansible Core Team (@ansible)