动作

当规则匹配条件时，它会触发该规则对应的动作。

注意

动作可以使用 Jinja 过滤器来转换和处理数据。有关可用过滤器的详细信息，请参阅 Jinja 过滤器，包括 regex_replace、basename、dirname 和 normpath，以及 Python 字符串方法。请注意，Jinja 过滤器不能在条件中使用。

支持以下动作

• run_playbook

• run_module

• run_job_template

• run_workflow_template

• set_fact

• post_event

• retract_fact

• print_event

• shutdown

• debug

• none

run_playbook

运行一个 Ansible playbook。

运行 playbook

Name	描述	必填
name	playbook 的名称，使用 FQCN（全限定集合名称），或者是绝对路径或相对路径。 如果是相对路径，它必须相对于执行 ansible-rulebook 命令的当前工作目录。	是
set_facts	布尔值，playbook 执行产生的事实（artifacts）将作为事实（facts）重新插入回规则集中。建议 playbook 应该使用 ansible.builtin.set_stats 任务来设置此数据。	否
post_events	布尔值，playbook 执行产生的事实将作为事件（events）重新插入回规则集中。建议 playbook 应该使用 ansible.builtin.set_stats 任务来设置此数据。	否
ruleset	要推送（post）事件或断言事实的规则集名称，默认为当前规则集。	否
retry	如果 playbook 执行失败，重试一次，布尔值 true|false	否
retries	如果 playbook 执行失败，重试的次数。整数值	否
delay	重试间隔，以秒为单位指定的整数值	否
verbosity	运行 playbook 时的详细程度，取值在 1-4 之间	否
var_root	如果事件是一个深度嵌套的字典，var_root 可以指定键名，其值应替换匹配的事件值。在有多个匹配事件的情况下，var_root 可以接受一个字典来处理数据。	否
extra_vars	作为额外变量传递给 playbook 的其他变量。	否
json_mode	布尔值，当 playbook 事件数据被 ansible-runner 处理时，将其作为 json 字符串发送到标准输出（stdout）	否
copy_files	布尔值，将本地 playbook 文件复制到 ansible-runner 项目目录，如果您是从 ansible 集合运行 playbook，则不需要此操作。	否
lock	当执行策略设置为 parallel（并行）时，可选的基于字符串的锁（lock）可确保按顺序执行此操作。它也可以是来自事件负载的字符串字段。锁是按规则集分配的，如果存在锁，所有使用相同锁的动作都将等待前一个动作完成。	否

run_module

运行一个 Ansible 模块

Name	描述	必填
name	模块名称，使用 FQCN（全限定集合名称）	是
module_args	传递给 Ansible 模块的参数	否
retry	如果模块执行失败，重试一次，布尔值 true|false。默认为 false	否
retries	如果模块执行失败，重试的次数。整数值，默认为 0	否
delay	重试间隔，整数值	否
verbosity	运行模块时的详细程度，取值在 1-4 之间	否
extra_vars	作为额外变量传递给 playbook 的其他变量。	否
json_mode	布尔值，当 playbook 事件数据被 ansible-runner 处理时，将其作为 json 字符串发送到标准输出（stdout）	否
set_facts	布尔值，模块执行产生的事实将作为事实重新插入回规则集中	否
post_events	布尔值，模块执行产生的事实将作为事件重新插入回规则集中	否
ruleset	要推送（post）事件或断言事实的规则集名称，默认为当前规则集。	否
var_root	如果事件是一个深度嵌套的字典，var_root 可以指定键名，其值应替换匹配的事件值。在有多个匹配事件的情况下，var_root 可以接受一个字典来处理数据。	否
lock	当执行策略设置为 parallel（并行）时，可选的基于字符串的锁（lock）可确保按顺序执行此操作。它也可以是来自事件负载的字符串字段。锁是按规则集分配的，如果存在锁，所有使用相同锁的动作都将等待前一个动作完成。	否
labels	可选的标签字符串列表，可以添加到控制器的作业中。要求在作业模板中启用“启动时提示标签”。如果未启用，标签将被忽略。ansible-rulebook 将添加一个名为“Activated by Event-Driven Ansible”的默认标签	否

run_job_template

运行作业模板。

注意

必须提供 --controller-url 以及 --controller-token 或 --controller-username 和 --controller-password 命令行选项才能使用此动作

为了访问 ansible_eda 命名空间下的事件信息，请务必勾选作业模板中变量字段的“启动时提示”。或者，可以创建一个包含变量 ansible_eda 的调查（survey）。类似地，如果您计划根据事件信息限制主机执行，请启用作业模板中“限制”字段的“启动时提示”。

注意

您可以定义环境变量 EDA_CONTROLLER_CONNECTION_LIMIT 来限制与控制器的并发连接数。默认值为 30。

注意

控制器 URL 是 ansible-rulebook 将尝试访问的 API 端点。如果您的 URL 中指定了路径，则其中应包含 api。如果您只提供了主机和端口而没有路径，为了向后兼容，我们将把 api 附加到 URL$ 后面。

Name	描述	必填
name	作业模板名称	是
organization	组织名称	是
include_events	是否应在发送到控制器的负载中包含匹配的事件。默认为 true	否
set_facts	作业模板执行产生的事实将作为事实重新插入回规则集中。建议 作业模板内的 playbook 应该使用 ansible.builtin.set_stats 任务来设置此数据。	否
post_events	作业模板执行产生的事实将作为事件重新插入回规则集中。建议 作业模板内的 playbook 应该使用 ansible.builtin.set_stats 任务来设置此数据。	否
ruleset	要推送（post）事件或断言事实的规则集名称，默认为当前规则集。	否
retry	如果作业模板执行失败，重试一次，布尔值 true|false	否
retries	如果作业模板执行失败，重试的次数。整数值	否
delay	重试间隔，以秒为单位指定的整数值	否
var_root	如果事件是一个深度嵌套的字典，var_root 可以指定键名，其值应替换匹配的事件值。在有多个匹配事件的情况下，var_root 可以接受一个字典来处理数据。	否
job_args	发送到作业模板启动 API 的附加参数。调查的所有答案和其他额外变量应设置在嵌套键 extra_vars 中。事件和事实也将自动包含在 extra_vars 中。可选地，如果 job_args 包含一个名为 limit 的属性，它可以用来覆盖从事件负载设置的限制。	否
lock	当执行策略设置为 parallel（并行）时，可选的基于字符串的锁（lock）可确保按顺序执行此操作。它也可以是来自事件负载的字符串字段。锁是按规则集分配的，如果存在锁，所有使用相同锁的动作都将等待前一个动作完成。	否
labels	可选的标签字符串列表，可以添加到控制器的作业中。要求在作业模板中启用“启动时提示标签”。如果未启用，标签将被忽略。ansible-rulebook 将添加一个名为“Activated by Event-Driven Ansible”的默认标签。如果标签解析为 None 或空字符串，它将被丢弃。如果有重复标签，重复的将被移除。例如 {{ event.payload.my_label | default(None) }} 如果属性不存在，我们将跳过该标签。	否
add_event_uuid_label	布尔字段，当设置为 true 时可以利用 event.meta.uuid 字段作为标签，您可以建立触发事件与其生成的作业之间的清晰可追溯性。	否

run_workflow_template

运行工作流模板。

注意

必须提供 --controller-url 以及 --controller-token 或 --controller-username 和 --controller-password 命令行选项才能使用此动作

注意

您可以定义环境变量 EDA_CONTROLLER_CONNECTION_LIMIT 来限制与控制器的并发连接数。默认值为 30。

注意

控制器 URL 是 ansible-rulebook 将尝试访问的 api 端点。如果您的 URL 中指定了路径，则其中应包含 api。如果您只提供了主机和端口而没有路径，为了向后兼容，我们将把 api 附加到 URL$ 后面。

Name	描述	必填
name	工作流模板名称	是
organization	组织名称	是
include_events	我们是否应该在发送到控制器的负载中包含匹配的事件。默认为 true。如果您的工作流模板没有“启动时提示额外变量”或“调查”规范，则必须将其设置为 false。	否
set_facts	工作流模板执行产生的事实将作为事实重新插入回规则集中	否
post_events	工作流模板执行产生的事实将作为事件重新插入回规则集中	否
ruleset	要推送（post）事件或断言事实的规则集名称，默认为当前规则集。	否
retry	如果工作流模板执行失败，重试一次，布尔值 true|false	否
retries	如果工作流模板执行失败，重试的次数。整数值	否
delay	重试间隔，以秒为单位指定的整数值	否
var_root	如果事件是一个深度嵌套的字典，var_root 可以指定键名，其值应替换匹配的事件值。在有多个匹配事件的情况下，var_root 可以接受一个字典来处理数据。	否
job_args	发送到工作流模板启动 API 的附加参数。调查的所有答案和其他额外变量应设置在嵌套键 extra_vars 中。事件和事实也将自动包含在 extra_vars 中。可选地，如果 job_args 包含一个名为 limit 的属性，它可以用来覆盖从事件负载设置的限制。	否
lock	当执行策略设置为 parallel（并行）时，可选的基于字符串的锁（lock）可确保按顺序执行此操作。它也可以是来自事件负载的字符串字段。锁是按规则集分配的，如果存在锁，所有使用相同锁的动作都将等待前一个动作完成。	否
labels	可选的标签字符串列表，可以添加到控制器的作业中。要求在作业模板中启用“启动时提示标签”。如果未启用，标签将被忽略。ansible-rulebook 将添加一个名为“Activated by Event-Driven Ansible”的默认标签。如果标签解析为 None 或空字符串，它将被丢弃。如果有重复标签，重复的将被移除。例如 {{ event.payload.my_label | default(None) }} 如果属性不存在，我们将跳过该标签。	否
add_event_uuid_label	布尔字段，当设置为 true 时可以利用 event.meta.uuid 字段作为标签，您可以建立触发事件与其生成的作业之间的清晰可追溯性。	否

post_event

将事件推送到规则引擎中正在运行的规则集

Name	描述	必填
event	要推送的事件字典	是
ruleset	要推送事件的规则集名称，默认为当前规则集名称	否

示例

action:
  post_event:
    ruleset: Test rules4
    event:
      j: 4

示例，使用分配保存的数据

name: multiple conditions
condition:
  all:
    - events.first << event.i == 0
    - events.second << event.i == 1
    - events.third << event.i == events.first.i + 2
action:
  post_event:
    ruleset: Test rules4
    event:
      data: "{{events.third}}"

事件和事实前缀具有规则范围，无法在规则之外访问。

请注意在访问事件结果时使用 Jinja 替换。

您还可以使用 Jinja 过滤器 在推送数据之前对其进行转换。

set_fact

将事实推送到规则引擎中正在运行的规则集

Name	描述	必填
fact	要推送的事实字典	是
ruleset	要推送事实的规则集名称，默认为当前规则集名称	否

示例

action:
    set_fact:
      ruleset: Test rules4
      fact:
        j: 1

示例，在多条件中使用通过分配保存的数据

name: multiple conditions
condition:
  all:
    - events.first << event.i == 0
    - events.second << event.i == 1
    - events.third << event.i == events.first.i + 2
action:
  set_fact:
    ruleset: Test rules4
    fact:
      data: "{{events.first}}"

示例，使用单条件保存的数据

name: single condition
condition: event.i == 23
action:
  set_fact:
    fact:
      myfact: "{{event.i}}"

一个 rulebook 可以有多个规则集，set_fact/retract_fact/post_event 允许您

针对 rulebook 内的不同规则集。目前您无法将一个事件断言到

多个规则集，它只能被断言到单个规则集。默认为当前

规则集。请注意在上述示例的动作中访问

事件结果时使用了 Jinja 替换。

retract_fact

从规则引擎中正在运行的规则集中移除事实

Name	描述	必填
fact	要移除的事实字典	是
ruleset	要撤销（retract）事实的规则集名称，默认为当前规则集名称	否
partial	请求撤销的事实是部分的，不包含所有键。默认为 true	否

示例

action:
  retract_fact:
    ruleset: Test rules4
    fact:
      j: 3

print_event

将事件写入标准输出（stdout）

Name	描述	必填
pretty	是否美化打印的布尔值	否
var_root	如果事件是一个深度嵌套的字典，var_root 可以指定键名，其值应替换匹配的事件值。在有多个匹配事件的情况下，var_root 可以接受一个字典来处理数据。	否

示例

action:
  print_event:
    pretty: true
    var_root: i

多事件匹配的示例

name: Multiple events with var_root
condition:
  all:
    - events.webhook << event.webhook.payload.url == "http://www.example.com"
    - events.kafka << event.kafka.message.channel == "red"
action:
  print_event:
    var_root:
      webhook.payload: webhook
      kafka.message: kafka

shutdown

关闭 ansible-rulebook

Name	描述	必填
delay	关于关机前等待多长时间（以秒为单位）的数值，默认 60.0	否
message	与此次关机相关联的消息	否
kind	关机类型可以是 graceful（优雅）或 now（立即）。默认是 graceful。	否

生成一个关机事件，该事件将终止 ansible-rulebook 进程。

如果您的 rulebook 中运行着多个规则集，发出关机指令将导致

所有其他规则集结束，需要注意正在运行的 playbook 可能

在其中一个规则集决定关机时受到影响。关机消息会

广播到所有正在运行的规则集。

示例

name: shutdown after 5 events
condition: event.i >= 5
action:
   shutdown:
     delay: 0.125
     message: Shutting down after 5 events

结果

当满足规则条件时，我们会得到如下返回结果

• 如果是多个条件，返回 events/facts

• 如果是单个条件，返回 event/fact

当调用您的 playbook 时，这些数据将作为 extra_vars 提供给它。

在以下所有示例中，您都会看到 facts/fact 分别是 events/event 的精确副本，

您可以在 playbook 中使用其中任何一个。

debug

调试 ansible-rulebook

Name	描述	必填
msg	一个简单的字符串或字符串数组，可以引用 event 或 events	否
var	要打印的变量，可以引用 event 或 events。使用 {{ }} 是可选的。	否

debug 动作试图模仿 ansible 中的 debug 命令。

如果没有提供参数，它将打印匹配的事件以及其他重要属性

msg 和 var 是互斥的，debug 中只能包含其中 1 个

msg 可以是单个字符串或字符串数组，带有对 event 或 events 的引用。

对于 var，使用 Jinja 风格的花括号是可选的，如下例所示

您可以使用 Jinja 过滤器 转换调试消息中的数据

示例

name: debug with single message
condition: event.i >= 5
action:
   debug:
     msg: Simple debug message

name: debug with multiple messages
condition: event.i >= 5
action:
   debug:
     msg:
        - "Message 1 {{ event }}"
        - Second Message

name: debug with var
condition: event.i >= 5
action:
   debug:
     var: event.i

none

无动作，在编写测试时很有用。不需要参数

常见问题解答 (FAQ)

问： 在 run_job_template、run_playbook、run_module 和 run_workflow_template 中使用 lock 的目的是什么？

答： 锁仅在您将执行策略设置为 parallel 且在不同系统上执行

多个作业，但希望根据某些属性进行顺序控制时才相关。例如，

正在执行作业的数据中心名称，您希望确保一次只有一个作业在

数据中心运行，但您想在其他数据中心运行其他作业。所有具有相同

锁的作业将按顺序运行。用户可以选择他们想要用作锁的内容，

它可以是来自事件负载的任何字符串属性，也可以是静态字符串，即您希望其他

动作并行运行，而特定动作按顺序运行。例如，如果您有

运行数据库备份的作业。锁不会对任务进行排队，它只是在锁空闲

且可用时运行它们。如果您需要对任务排序，可以继续为规则使用多个动作。您可以

使用工作流模板而不是作业模板来执行其他排序。

示例

name: sample rule
condition: event.level == "error"
action:
  run_job_template:
    name: Fix My Datacenter
    organization: Default
    lock: "{{ event.datacenter }}"