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

注意

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

概要

• 动态加载并执行指定的角色作为任务。

• 只能在允许 Ansible 任务的地方使用 - 在 pre_tasks、tasks 或 post_tasks 剧本对象中，或作为角色中的任务。

• 任务级关键字、循环和条件语句仅适用于 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 是否公开给剧本。如果设置为 true，则变量将对 include_role 任务之后的任务可用。此功能不同于在 roles 标题下列出的角色或 ansible.builtin.import_role 的标准变量公开，因为它们在剧本解析时公开给剧本，并且对更早的角色和任务也可用。 选择 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	允许使用“标签”关键字来控制此操作的选择以进行执行
until	支持：完整	表示此操作是否服从 until/retry/poll 关键字

备注

注意

• 处理程序和可用于整个剧本。

• 在 Ansible 2.4 之后，您可以使用 ansible.builtin.import_role 用于静态行为，而使用此操作用于动态行为。

另请参阅

另请参阅

ansible.builtin.import_playbook

导入剧本。

ansible.builtin.import_role

将角色导入剧本。

ansible.builtin.import_tasks

导入任务列表。

ansible.builtin.include_tasks

动态包含任务列表。

重复使用 Ansible 工件

有关包含和导入剧本、角色和任务的更多信息。

示例

- 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 Core 团队 (@ansible)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 通讯