ansible.builtin.include_role – Load and execute a role¶
Note
This module is part of ansible-base
and included in all Ansible
installations. In most cases, you can use the short module name
include_role even without specifying the collections:
keyword.
Despite that, 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
playbook 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.
Parameters¶
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)