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 |
Comments |
---|---|
Overrides the role’s metadata setting to allow using a role more than once with the same parameters. Choices:
|
|
Accepts a hash of task keywords (e.g. |
|
File to load from a role’s Default: “main” |
|
File to load from a role’s Default: “main” |
|
The name of the role to be executed. |
|
This option dictates whether the role’s Choices:
|
|
Perform role argument spec validation if an argument spec is defined. Choices:
|
|
File to load from a role’s Default: “main” |
|
File to load from a role’s Default: “main” |
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)