ansible.builtin.include_role 模块 – 加载并执行角色

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，您也可以使用简短的模块名称 include_role。但是，我们建议您使用完全限定的集合名称 (FQCN) ansible.builtin.include_role，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合冲突。

概要 

动态加载并执行指定的角色作为任务。
只能在允许使用 Ansible 任务的地方使用 - 在 pre_tasks、tasks 或 post_tasks play 对象内，或者作为角色内的任务。
任务级别的关键字、循环和条件仅适用于 include_role 语句本身。
要将关键字应用于角色内的任务，请使用 apply 选项传递它们，或者改用 ansible.builtin.import_role。
忽略一些关键字，例如 until 和 retries。
此模块也支持 Windows 目标。
在处理程序中不起作用。

参数 

参数	注释
allow_duplicates 布尔值	覆盖角色的元数据设置，以允许使用具有相同参数的角色多次。选项 `false` `true` ←（默认）
apply 字符串在 Ansible 2.7 中添加	接受任务关键字的哈希值（例如 `tags`、`become`），这些关键字将应用于包含角色中的所有任务。
defaults_from 字符串	要从角色的 `defaults/` 目录加载的文件。默认值： `"main"`
handlers_from 字符串在 Ansible 2.8 中添加	要从角色的 `handlers/` 目录加载的文件。默认值： `"main"`
name 字符串 / 必需	要执行的角色的名称。
public 布尔值在 Ansible 2.7 中添加	此选项决定角色的 `vars` 和 `defaults` 是否向 play 公开。如果设置为 `true`，则变量将可用于 `include_role` 任务之后的任务。此功能与 `roles` 标题下列出的角色的标准变量公开方式不同，或者ansible.builtin.import_role，因为它们在 playbook 解析时公开给 play，并且也可用于较早的角色和任务。选项 `false` ←（默认） `true`
rolespec_validate 布尔值在 ansible-core 2.11 中添加	如果定义了参数规范，则执行角色参数规范验证。选项 `false` `true` ←（默认）
tasks_from 字符串	要从角色的 `tasks/` 目录加载的文件。默认值： `"main"`
vars_from 字符串	要从角色的 `vars/` 目录加载的文件。默认值： `"main"`

属性 

属性	支持	描述
action	支持：无虽然此操作在控制器上本地执行，但它不受操作插件的管理	指示此操作具有相应的操作插件，因此可以在控制器上执行某些选项
async	支持：无	支持与 `async` 关键字一起使用
become	支持：无	可以与 become 关键字一起使用
bypass_host_loop	支持：无	强制执行不按主机执行的“全局”任务，这会绕过按主机模板、串行、限制和其他循环考虑事项条件语句将像使用 `run_once` 一样工作，使用的变量将来自第一个可用的主机此操作在锁定步骤策略之外无法正常工作
bypass_task_loop	支持：无	这些任务忽略 `loop` 和 `with_` 关键字
check_mode	支持：完整	可以在 check_mode 中运行，并返回更改的状态预测，而无需修改目标，如果不支持，则会跳过该操作。
connection	支持：无	使用目标配置的连接信息在其上执行代码
core	支持：完整	这是“核心引擎”功能，并非像大多数任务操作那样实现，因此无法通过插件系统以任何方式覆盖它。
delegation	支持：无由于没有连接和事实，因此委托包含没有任何意义	可以与 delegate_to 和相关关键字结合使用
diff_mode	支持：无	在 diff 模式下，将返回有关已更改（或可能需要在 check_mode 中更改）的内容的详细信息
ignore_conditional	支持：无	该操作不受条件执行的影响，因此将忽略 `when:` 关键字
platform	平台：全部	可以对其进行操作的目标操作系统/系列
tags	支持：完整此操作会解释标签，但不会自动由包含的任务继承，请参阅 `apply`	允许使用“tags”关键字来控制此操作的执行选择
until	支持：完整	表示此操作是否遵循 until/retry/poll 关键字

备注 

注意

处理程序和对整个 play 可用。
在 Ansible 2.4 之后，您可以使用 ansible.builtin.import_role 来获得静态行为，并使用此操作来获得动态行为。

另请参阅 

另请参阅

ansible.builtin.import_playbook: 导入 playbook。
ansible.builtin.import_role: 将角色导入到 play 中。
ansible.builtin.import_tasks: 导入任务列表。
ansible.builtin.include_tasks: 动态包含任务列表。
重用 Ansible 项目: 有关包含和导入 playbook、角色和任务的更多信息。

示例 

- 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

作者

Ansible 核心团队 (@ansible)