ansible.builtin.include_role module – 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 Fully Qualified Collection Name (FQCN) ansible.builtin.include_role
for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
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 (for example |
|
File to load from a role’s Default: |
|
File to load from a role’s Default: |
|
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: |
|
File to load from a role’s Default: |
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: none While this action executes locally on the controller it is not governed by an action plugin |
Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller |
|
Support: none |
Supports being used with the |
|
Support: none |
Is usable alongside become keywords |
|
Support: none |
Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations Conditionals will work as if This action will not work normally outside of lockstep strategies |
|
Support: none |
These tasks ignore the |
|
Support: full |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
Support: none |
Uses the target’s configured connection information to execute code on it |
|
Support: full |
This is a ‘core engine’ feature and is not implemented like most task actions, so it is not overridable in any way via the plugin system. |
|
Support: none Since there are no connection nor facts, there is no sense in delegating includes |
Can be used in conjunction with delegate_to and related keywords |
|
Support: none |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Support: none |
The action is not subject to conditional execution so it will ignore the |
|
Platforms: all |
Target OS/families that can be operated against |
|
Support: full Tags are interpreted by this action but are not automatically inherited by the include tasks, see |
Allows for the ‘tags’ keyword to control the selection of this action for execution |
|
Support: full |
Denotes if this action obeys until/retry/poll keywords |
Notes
Note
Handlers and are made available to the whole play.
After Ansible 2.4, you can use ansible.builtin.import_role for static behaviour and this action for dynamic one.
See Also
See also
- ansible.builtin.import_playbook
Import a playbook.
- ansible.builtin.import_role
Import a role into a play.
- ansible.builtin.import_tasks
Import a task list.
- ansible.builtin.include_tasks
Dynamically include a task list.
- Re-using Ansible artifacts
More information related to including and importing playbooks, roles and tasks.
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