Rulebooks

Rulebooks 包含一个规则集 (rulesets) 列表。rulebook 中的每个规则集
都应具有唯一的名称，因为它们在运行时可以根据名称
向彼此发送事件。如果一个 rulebook 包含多个规则集，
关闭其中一个规则集将关闭所有其他正在运行的规则集。

Rulesets（规则集）

一个规则集具有以下属性：

Name	描述	必填
name	用于标识规则集的名称。每个规则集在整个 rulebook 中必须具有唯一的名称。	是
sources	一个或多个将为 ansible-rulebook 生成事件的源列表。请参阅事件源 (Event Sources)	是
rules	一条或多条规则的列表。请参阅规则 (Rules)	是
hosts	类似于 Ansible playbook 中的 hosts。该值用于需要清单 (inventory) 的操作（例如：run_playbook 或 run_module）。它不用于控制器操作（例如：run_job_template, run_workflow_template）	是
gather_facts	在启动时从主机收集 artifact 以在规则中使用（默认值：false）	否
default_events_ttl	保留部分匹配事件的时间（默认值：2 小时）	否
execution_strategy	操作执行方式，顺序或并行（默认值：sequential）。对于顺序策略，我们在触发下一个操作之前会等待每个操作完成。	否
match_multiple_rules	规则引擎在初始匹配后是否应继续处理其他规则。此选项将在规则引擎中缓存事件，时间为 default_events_ttl。默认值为 2 小时，这会导致在事件被清除之前内存膨胀。	否

规则集 应该 在 rulebook 内具有唯一的名称，每个规则集
在规则引擎中作为一个单独的会话运行。每个规则集的
事件和事实 (facts) 是分开保存的。在运行时，通过 action，规则集可以
向自身或 rulebook 中的其他规则集发送事件或事实。

default_events_ttl 的时间采用以下格式：
default_events_ttl : nnn seconds|minutes|hours|days
例如：default_events_ttl : 3 hours
如果规则集未定义此属性，则由规则引擎
强制执行的默认事件 TTL 为 2 小时

当我们启动 rulebook 时，如果 gather_facts 设置为 true，
我们可以选择性地从不同的主机收集 artifact。这些主机数据随后被上传到
规则引擎作为事实，以便在运行时根据传入的事件
在不同规则中进行评估。每个主机数据在规则引擎中单独存储。要访问
主机名，请使用 fact.meta.hosts 属性。例如：

- name: Example
  hosts: all
  gather_facts: true
  sources:
    - name: range
      eda.builtin.range:
        limit: 5
  rules:
    - name: r1
      condition: event.i == 1
      action:
        debug:

    - name: "Host specific rule"
      condition:
        all:
          - fact.ansible_os_family == "linux"
          - fact.meta.hosts == "my-host"
          - event.i == 4
      action:
        debug:

规则集 必须 包含一个或多个源插件，配置参数
可以在源插件类型之后指定。源插件
还可以配置事件过滤器，允许你在将数据传递给
规则引擎之前对其进行转换。过滤器还可以用于
限制传递给规则引擎的数据。源插件由
ansible-rulebook 启动并在后台运行，将事件
放入队列中传递给规则引擎。
当源插件结束时，我们会自动生成一个关闭事件，随后规则集
终止，进而终止 ansible-rulebook。

规则集 必须 包含一条或多条规则。规则由规则引擎评估。
规则引擎将根据传入的事件评估规则的所有必需条件。
如果规则中的条件匹配，我们将触发操作。操作可以
运行 playbook、模块，或向同一个规则集或不同的
规则集发起另一个事件或事实。当规则集接收到来自源插件的
关闭事件，或者由其中一个匹配规则调用关闭操作时，规则集停止执行。

包含多个源

在 rulebook 中，你可以配置一个或多个源，每个源以不同的格式发出事件。

示例

sources:
  - eda.builtin.range:
      limit: 6
  - eda.builtin.webhook:
      port: 5000

条件可以匹配来自任何一个源的事件

rules:
  - name:
    condition: event.i == 2
    action:
      debug:

  - name:
    condition: event.payload.status == "OK"
    action:
      debug:

为了避免名称冲突，源数据结构可以使用嵌套键。

注意事项

如果任何一个源终止，它将关闭整个引擎。来自其他源的所有事件可能会丢失。

使用加密字符串 (Vaulted strings)

rulebook 引用的敏感数据必须由 ansible-vault cli 进行加密。加密字符串可以直接嵌入在 rulebook 中，或者放在变量文件中并通过 extra vars 在 rulebook 中引用。只有源插件或操作的参数可以被加密。以下是包含嵌入式加密字符串的 rulebook 示例：

action:
  run_playbook:
    name: !vault |
      $ANSIBLE_VAULT;1.1;AES256
      34363839636133343562323339363066616165326363626133616264326565336633386438333936
      3833303135313062343861353765383633643931613535340a356532376531656566643133303833
      39396335636439363838386430346532623633303763626362646435633736613834333534663532
      3966643666326535620a626166616465386639373136396236336161333836303664633330356134
      30396661336162343734353837366437383433343461333564663236313639376633616238633463
      3765626362303336303761373538343939396434346261356164
    extra_vars:
      foo: "{{ foo_var }}"

以下是包含加密字符串的变量文件示例

---
foo_var: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  33353433303339303239653832383938613664323063313065326365323232366537613762303736
  3864333763656663646332653738316135383562343962300a653333303538353132366336323337
  39366365303563386636613834633463303835613461393066643632356338393038306366616631
  3534326432333466390a303037323232663239636132343836313434333139623530386134326130
  3465
match_this_int: 2
警告

使用 Ansible Vault 加密仅保护“静态数据 (data at rest)”。一旦内容被解密（“使用中数据 (data in use)”），rulebook 和源插件作者有责任避免任何秘密泄露。

用于解密加密字符串的密码可以通过以下命令行参数之一提供，即 –vault-id, –vault-password-file, 或 –ask-vault-pass。如果仅使用一个密码文件，也可以通过环境变量 EDA_VAULT_PASSWORD_FILE 设置。

为所有加密字符串接收一个密码的示例

ansible-rulebook --rulebook rules_with_vaulted_vars.yml --vault-password-file mypassword.txt

接收多个密码的示例

ansible-rulebook --rulebook rules.yml --vars vars.yml --vault-id pass1@mypassword1.txt --vault-id pass2@mypassword2.txt

更多信息请参阅用法 (Usage) 页面。

请注意，如果 ansible-rulebook cli 版本为 1.0.4 或更早版本，则不支持 rulebook 或变量文件中的加密字符串。你会看到类似 ERROR - Terminating could not determine a constructor for the tag ‘!vault’ 的错误

分发 rulebooks

分发 rulebook 的推荐方法是通过 collection。在这种情况下，rulebook 文件应放置在 extensions/eda/rulebooks 文件夹下，并在命令行参数中使用 FQCN 引用。即使存储库不是真正的 collection，Eda-server 项目也会对项目遵循此路径。