Playbook 关键字

以下是通用 Playbook 对象中可用的关键字。关键字是配置 Ansible 行为的多个来源之一。有关每个来源相对优先级的详细信息，请参阅 控制 Ansible 的行为：优先级规则。

注意

请注意

• 此处未反映指令的别名，也不包含可变指令。例如，任务中的 action 可以替换为任何 Ansible 模块的名称。

• 目前这些关键字没有 version_added（添加版本）信息

• 某些关键字是为其内部的对象设置默认值，而不是为对象本身设置

Play

any_errors_fatal

强制任何主机上未处理的任务错误传播到所有主机并结束当前 Play。

become

布尔值，控制在执行 Task 时是否使用权限提升。由 become 插件实现。请参阅 Become 插件。

become_exe

用于提升权限的可执行文件路径。由 become 插件实现。请参阅 Become 插件。

become_flags

当 become 为 True 时，传递给权限提升程序的标志字符串。

become_method

使用哪种权限提升方法（例如 sudo 或 su）。

become_user

使用权限提升后“成为”的用户。远程/登录用户必须具有成为此用户的权限。

check_mode

布尔值，控制任务是正常运行，还是避免对目标进行更改并尝试报告其将执行的操作（检查模式/试运行）。请参阅 验证任务：检查模式和差异模式。

collections

用于搜索模块、插件和角色的集合（collection）命名空间列表。请参阅 在 Playbook 中使用集合

注意

角色内的任务不会从 Play 继承 collections 的值。要让角色搜索集合列表，请在角色内的 meta/main.yml 中使用 collections 关键字。

connection

允许更改用于在目标上执行任务的连接插件。请参阅 使用连接插件。

debugger

根据任务结果的状态启用调试任务。请参阅 调试任务。

diff

开关，用于决定是否让任务返回“diff”（差异）信息。

environment

一个会被转换为环境变量的字典，在任务执行时提供给任务。这只能与模块一起使用。它不支持任何其他类型的插件、Ansible 本身或其配置，它仅为负责执行任务的代码设置变量。不建议使用此方法传递机密数据。

fact_path

为由 gather_facts 控制的事实收集插件设置 fact path（事实路径）选项。

force_handlers

即使主机在 Play 期间失败，也会强制对这些主机执行通知的处理程序（handler）。如果 Play 本身失败，则不会触发。

gather_facts

布尔值，控制 Play 是否自动运行“setup”任务来为各主机收集事实。

gather_subset

允许向由 gather_facts 控制的事实收集插件传递子集选项。

gather_timeout

允许为由 gather_facts 控制的事实收集插件设置超时时间。

handlers

包含被视为处理程序（handler）的任务的部分，它们不会正常执行，仅在每个任务部分完成后被通知时执行。处理程序的 listen 字段不支持模板化。

hosts

组、主机或主机模式的列表，解析为 Play 目标的主机列表。

ignore_errors

布尔值，允许忽略任务失败并继续执行 Play。它不影响连接错误。

ignore_unreachable

布尔值，允许忽略因主机无法访问而导致的任务失败，并继续执行 Play。这不会影响其他任务错误（请参阅 ignore_errors），但对不稳定的/临时的主机组非常有用。

max_fail_percentage

用于在当前批次中达到给定比例的主机失败后中止运行。此功能仅适用于线性（linear）或基于线性的策略。

module_defaults

为模块指定默认参数值。

name

标识符。可用于文档说明，或在任务/处理程序中使用。

no_log

布尔值，控制信息披露。

order

控制执行 Play 时主机的使用排序。可能的值有 inventory（默认）、sorted、reverse_sorted、reverse_inventory 和 shuffle。

port

用于覆盖连接中使用的默认端口。

post_tasks

在 tasks 部分之后执行的任务列表。

pre_tasks

在 roles 之前执行的任务列表。

remote_user

用于通过连接插件登录目标的用户。

roles

要导入到 Play 中的角色列表

run_once

布尔值，将绕过主机循环，强制任务尝试在第一个可用的主机上执行，之后将任何结果和事实应用于同一批次中的所有活跃主机。

serial

明确定义 Ansible 如何在 Play 的目标上分批执行当前 Play。请参阅 使用 serial 设置批处理大小。

strategy

允许为 Play 选择要使用的策略插件。请参阅 策略插件。

tags

应用于任务或包含任务的标签，这允许从命令行选择任务的子集。

tasks

在 Play 中执行的主要任务列表，它们在 roles 之后且在 post_tasks 之前运行。

调节 (throttle)

在任务、块和 Playbook 级别限制并发任务运行的数量。这独立于 forks 和 serial 设置，但不能设置高于这些限制的值。例如，如果 forks 设置为 10，throttle 设置为 15，则最多并行操作 10 台主机。

timeout

任务操作执行的时间限制，如果超出，Ansible 将中断该进程。超时不包括模板化或循环时间。

validate_argspec

未记录！！

vars

变量的字典/映射

vars_files

要在 Play 中包含的变量文件列表。

vars_prompt

需要提示输入值的变量列表。

Role

any_errors_fatal

强制任何主机上未处理的任务错误传播到所有主机并结束当前 Play。

become

布尔值，控制在执行 Task 时是否使用权限提升。由 become 插件实现。请参阅 Become 插件。

become_exe

用于提升权限的可执行文件路径。由 become 插件实现。请参阅 Become 插件。

become_flags

当 become 为 True 时，传递给权限提升程序的标志字符串。

become_method

使用哪种权限提升方法（例如 sudo 或 su）。

become_user

使用权限提升后“成为”的用户。远程/登录用户必须具有成为此用户的权限。

check_mode

布尔值，控制任务是正常运行，还是避免对目标进行更改并尝试报告其将执行的操作（检查模式/试运行）。请参阅 验证任务：检查模式和差异模式。

collections

用于搜索模块、插件和角色的集合（collection）命名空间列表。请参阅 在 Playbook 中使用集合

注意

角色内的任务不会从 Play 继承 collections 的值。要让角色搜索集合列表，请在角色内的 meta/main.yml 中使用 collections 关键字。

connection

允许更改用于在目标上执行任务的连接插件。请参阅 使用连接插件。

debugger

根据任务结果的状态启用调试任务。请参阅 调试任务。

delegate_facts

布尔值，允许将事实应用于委派主机，而不是 inventory_hostname。

delegate_to

用于执行任务的主机，而不是目标（inventory_hostname）。来自委派主机的连接变量也将用于该任务。

diff

开关，用于决定是否让任务返回“diff”（差异）信息。

environment

一个会被转换为环境变量的字典，在任务执行时提供给任务。这只能与模块一起使用。它不支持任何其他类型的插件、Ansible 本身或其配置，它仅为负责执行任务的代码设置变量。不建议使用此方法传递机密数据。

ignore_errors

布尔值，允许忽略任务失败并继续执行 Play。它不影响连接错误。

ignore_unreachable

布尔值，允许忽略因主机无法访问而导致的任务失败，并继续执行 Play。这不会影响其他任务错误（请参阅 ignore_errors），但对不稳定的/临时的主机组非常有用。

module_defaults

为模块指定默认参数值。

name

标识符。可用于文档说明，或在任务/处理程序中使用。

no_log

布尔值，控制信息披露。

port

用于覆盖连接中使用的默认端口。

remote_user

用于通过连接插件登录目标的用户。

run_once

布尔值，将绕过主机循环，强制任务尝试在第一个可用的主机上执行，之后将任何结果和事实应用于同一批次中的所有活跃主机。

tags

应用于任务或包含任务的标签，这允许从命令行选择任务的子集。

调节 (throttle)

在任务、块和 Playbook 级别限制并发任务运行的数量。这独立于 forks 和 serial 设置，但不能设置高于这些限制的值。例如，如果 forks 设置为 10，throttle 设置为 15，则最多并行操作 10 台主机。

timeout

任务操作执行的时间限制，如果超出，Ansible 将中断该进程。超时不包括模板化或循环时间。

vars

变量的字典/映射

when

条件表达式，决定任务的迭代是否运行。

Block

always

块中的任务列表，无论块中是否有错误，它们都会执行。

any_errors_fatal

强制任何主机上未处理的任务错误传播到所有主机并结束当前 Play。

become

布尔值，控制在执行 Task 时是否使用权限提升。由 become 插件实现。请参阅 Become 插件。

become_exe

用于提升权限的可执行文件路径。由 become 插件实现。请参阅 Become 插件。

become_flags

当 become 为 True 时，传递给权限提升程序的标志字符串。

become_method

使用哪种权限提升方法（例如 sudo 或 su）。

become_user

使用权限提升后“成为”的用户。远程/登录用户必须具有成为此用户的权限。

block

块中的任务列表。

check_mode

布尔值，控制任务是正常运行，还是避免对目标进行更改并尝试报告其将执行的操作（检查模式/试运行）。请参阅 验证任务：检查模式和差异模式。

collections

用于搜索模块、插件和角色的集合（collection）命名空间列表。请参阅 在 Playbook 中使用集合

注意

角色内的任务不会从 Play 继承 collections 的值。要让角色搜索集合列表，请在角色内的 meta/main.yml 中使用 collections 关键字。

connection

允许更改用于在目标上执行任务的连接插件。请参阅 使用连接插件。

debugger

根据任务结果的状态启用调试任务。请参阅 调试任务。

delegate_facts

布尔值，允许将事实应用于委派主机，而不是 inventory_hostname。

delegate_to

用于执行任务的主机，而不是目标（inventory_hostname）。来自委派主机的连接变量也将用于该任务。

diff

开关，用于决定是否让任务返回“diff”（差异）信息。

environment

一个会被转换为环境变量的字典，在任务执行时提供给任务。这只能与模块一起使用。它不支持任何其他类型的插件、Ansible 本身或其配置，它仅为负责执行任务的代码设置变量。不建议使用此方法传递机密数据。

ignore_errors

布尔值，允许忽略任务失败并继续执行 Play。它不影响连接错误。

ignore_unreachable

布尔值，允许忽略因主机无法访问而导致的任务失败，并继续执行 Play。这不会影响其他任务错误（请参阅 ignore_errors），但对不稳定的/临时的主机组非常有用。

module_defaults

为模块指定默认参数值。

name

标识符。可用于文档说明，或在任务/处理程序中使用。

no_log

布尔值，控制信息披露。

notify

当任务返回“changed=True”状态时要通知的处理程序列表。

port

用于覆盖连接中使用的默认端口。

remote_user

用于通过连接插件登录目标的用户。

rescue

block 中的任务列表，如果在主 block 列表中出现任务错误，则运行这些任务。

run_once

布尔值，将绕过主机循环，强制任务尝试在第一个可用的主机上执行，之后将任何结果和事实应用于同一批次中的所有活跃主机。

tags

应用于任务或包含任务的标签，这允许从命令行选择任务的子集。

调节 (throttle)

在任务、块和 Playbook 级别限制并发任务运行的数量。这独立于 forks 和 serial 设置，但不能设置高于这些限制的值。例如，如果 forks 设置为 10，throttle 设置为 15，则最多并行操作 10 台主机。

timeout

任务操作执行的时间限制，如果超出，Ansible 将中断该进程。超时不包括模板化或循环时间。

vars

变量的字典/映射

when

条件表达式，决定任务的迭代是否运行。

Task

action

任务要执行的“动作”，它通常转换为 C(module) 或动作插件。

any_errors_fatal

强制任何主机上未处理的任务错误传播到所有主机并结束当前 Play。

args

向任务添加参数的辅助方式。接受一个字典，其中键映射到选项和值。

async

如果 C(action) 支持，则异步运行任务；值为最长运行时间（秒）。

become

布尔值，控制在执行 Task 时是否使用权限提升。由 become 插件实现。请参阅 Become 插件。

become_exe

用于提升权限的可执行文件路径。由 become 插件实现。请参阅 Become 插件。

become_flags

当 become 为 True 时，传递给权限提升程序的标志字符串。

become_method

使用哪种权限提升方法（例如 sudo 或 su）。

become_user

使用权限提升后“成为”的用户。远程/登录用户必须具有成为此用户的权限。

changed_when

覆盖任务正常“changed”状态的条件表达式。

check_mode

布尔值，控制任务是正常运行，还是避免对目标进行更改并尝试报告其将执行的操作（检查模式/试运行）。请参阅 验证任务：检查模式和差异模式。

collections

用于搜索模块、插件和角色的集合（collection）命名空间列表。请参阅 在 Playbook 中使用集合

注意

角色内的任务不会从 Play 继承 collections 的值。要让角色搜索集合列表，请在角色内的 meta/main.yml 中使用 collections 关键字。

connection

允许更改用于在目标上执行任务的连接插件。请参阅 使用连接插件。

debugger

根据任务结果的状态启用调试任务。请参阅 调试任务。

delay

重试之间的延迟秒数。此设置仅与 until 结合使用。

delegate_facts

布尔值，允许将事实应用于委派主机，而不是 inventory_hostname。

delegate_to

用于执行任务的主机，而不是目标（inventory_hostname）。来自委派主机的连接变量也将用于该任务。

diff

开关，用于决定是否让任务返回“diff”（差异）信息。

environment

一个会被转换为环境变量的字典，在任务执行时提供给任务。这只能与模块一起使用。它不支持任何其他类型的插件、Ansible 本身或其配置，它仅为负责执行任务的代码设置变量。不建议使用此方法传递机密数据。

failed_when

覆盖任务正常“failed”状态的条件表达式。

ignore_errors

布尔值，允许忽略任务失败并继续执行 Play。它不影响连接错误。

ignore_unreachable

布尔值，允许忽略因主机无法访问而导致的任务失败，并继续执行 Play。这不会影响其他任务错误（请参阅 ignore_errors），但对不稳定的/临时的主机组非常有用。

local_action

与 action 相同，但还暗示 delegate_to: localhost

loop

获取任务要迭代的列表，将每个列表元素保存到 item 变量中（可通过 loop_control 配置）

loop_control

此处的几个键允许您修改/设置任务中的循环行为。请参阅 向循环添加控制。

module_defaults

为模块指定默认参数值。

name

标识符。可用于文档说明，或在任务/处理程序中使用。

no_log

布尔值，控制信息披露。

notify

当任务返回“changed=True”状态时要通知的处理程序列表。

poll

设置异步任务的轮询间隔（秒，默认 10 秒）。

port

用于覆盖连接中使用的默认端口。

register

将包含任务状态和模块返回数据的变量名称。

remote_user

用于通过连接插件登录目标的用户。

retries

在 until 循环中放弃前的重试次数。此设置仅与 until 结合使用。

run_once

布尔值，将绕过主机循环，强制任务尝试在第一个可用的主机上执行，之后将任何结果和事实应用于同一批次中的所有活跃主机。

tags

应用于任务或包含任务的标签，这允许从命令行选择任务的子集。

调节 (throttle)

在任务、块和 Playbook 级别限制并发任务运行的数量。这独立于 forks 和 serial 设置，但不能设置高于这些限制的值。例如，如果 forks 设置为 10，throttle 设置为 15，则最多并行操作 10 台主机。

timeout

任务操作执行的时间限制，如果超出，Ansible 将中断该进程。超时不包括模板化或循环时间。

until

此关键字暗示了一个“retries 循环”，它将持续运行，直到满足此处提供的条件或达到 retries 限制。

vars

变量的字典/映射

when

条件表达式，决定任务的迭代是否运行。

with_<lookup_plugin>

与 loop 相同，但会自动添加任何查找插件的输出以生成项目列表。