On this page
ansible.builtin.include_role – Load and execute a role
Note
This module is part of ansible-core
and included in all Ansible installations. In most cases, you can use the short module name include_role
even without specifying the collections:
keyword. However, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.
New in version 2.2: of ansible.builtin
Synopsis
- Dynamically loads and executes a specified role as a task.
- May be used only where Ansible tasks are allowed - inside
pre_tasks
,tasks
, orpost_tasks
play objects, or as a task inside a role. - Task-level keywords, loops, and conditionals apply only to the
include_role
statement itself. - To apply keywords to the tasks within the role, pass them using the
apply
option or use ansible.builtin.import_role instead. - Ignores some keywords, like
until
andretries
. - This module is also supported for Windows targets.
- Does not work in handlers.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
allow_duplicates
boolean
|
|
Overrides the role's metadata setting to allow using a role more than once with the same parameters.
|
apply
string
added in 2.7 of ansible.builtin
|
Accepts a hash of task keywords (e.g. tags , become ) that will be applied to all tasks within the included role.
|
|
defaults_from
string
|
Default:
"main"
|
File to load from a role's defaults/ directory.
|
handlers_from
string
added in 2.8 of ansible.builtin
|
Default:
"main"
|
File to load from a role's handlers/ directory.
|
name
string / required
|
The name of the role to be executed.
|
|
public
boolean
added in 2.7 of ansible.builtin
|
|
This option dictates whether the role's vars and defaults are exposed to the play. If set to yes the variables will be available to tasks following the include_role task. This functionality differs from standard variable exposure for roles listed under the roles header or import_role as they are exposed to the play at playbook parsing time, and available to earlier roles and tasks as well.
|
rolespec_validate
boolean
added in 2.11 of ansible.builtin
|
|
Perform role argument spec validation if an argument spec is defined.
|
tasks_from
string
|
Default:
"main"
|
File to load from a role's tasks/ directory.
|
vars_from
string
|
Default:
"main"
|
File to load from a role's vars/ directory.
|
Notes
Note
- Handlers are made available to the whole play.
- Before Ansible 2.4, as with
include
, this task could be static or dynamic, If static, it implied that it won’t need templating, loops or conditionals and will show included tasks in the--list
options. Ansible would try to autodetect what is needed, but you can setstatic
toyes
orno
at task level to control this. - After Ansible 2.4, you can use ansible.builtin.import_role for
static
behaviour and this action fordynamic
one.
See Also
See also
- ansible.builtin.import_playbook
-
The official documentation on the ansible.builtin.import_playbook module.
- ansible.builtin.import_role
-
The official documentation on the ansible.builtin.import_role module.
- ansible.builtin.import_tasks
-
The official documentation on the ansible.builtin.import_tasks module.
- ansible.builtin.include_tasks
-
The official documentation on the ansible.builtin.include_tasks module.
- Including and importing
-
More information related to including and importing playbooks, roles and tasks.
Examples
- include_role:
name: myrole
- name: Run tasks/other.yaml instead of 'main'
include_role:
name: myrole
tasks_from: other
- name: Pass variables to role
include_role:
name: myrole
vars:
rolevar1: value from task
- name: Use role in loop
include_role:
name: '{{ roleinputvar }}'
loop:
- '{{ roleinput1 }}'
- '{{ roleinput2 }}'
loop_control:
loop_var: roleinputvar
- name: Conditional role
include_role:
name: myrole
when: not idontwanttorun
- name: Apply tags to tasks within included file
include_role:
name: install
apply:
tags:
- install
tags:
- always
Authors
- Ansible Core Team (@ansible)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/include_role_module.html