include_role – Load and execute a role
include_role – Load and execute a role
New in version 2.2.
Synopsis
- Loads and executes a role as a task dynamically. This frees roles from the
roles:
directive and allows them to be treated more as tasks. - Unlike import_role, most keywords, including loop, with_items, and conditionals, apply to this statement.
- The do until loop is not supported on include_role.
- This module is also supported for Windows targets.
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 - added in 2.7 |
Accepts a hash of task keywords (e.g. | |
defaults_from - |
Default: "main" |
File to load from a role's |
name - / required |
The name of the role to be executed. | |
private - |
This option is a no op, and the functionality described in previous versions was not implemented. This option will be removed in Ansible v2.8. | |
public boolean added in 2.7 |
|
This option dictates whether the role's |
tasks_from - |
Default: "main" |
File to load from a role's |
vars_from - |
Default: "main" |
File to load from a role's |
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 import_role for ‘static’ behaviour and this action for ‘dynamic’ one.
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: myrole
with_items:
- '{{ 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
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Ansible Core Team (@ansible)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/include_role_module.html