插件生命周期

事件驱动 Ansible (EDA) 插件遵循定义的生命周期，以确保在插件演进、被替换或被移除时能够平稳过渡。这种生命周期管理有助于集合 (collection) 维护者在迁移期间向用户传达变更，同时保持向后兼容性。

理解插件生命周期

Ansible-rulebook 支持插件生命周期的以下阶段：弃用、移除 (墓碑机制) 和 重定向。

弃用 (Deprecation)

当插件需要被替换或发生重大变更时，它将进入弃用阶段。被弃用的插件：

• 继续正常运行

• 在使用时显示弃用警告

• 指明将在哪个版本或何时被移除

• 提供关于迁移替代方案的指导

• 在过渡期内保留在集合中

移除 (墓碑机制/Tombstoning)

在弃用期结束后，插件将从集合中移除。墓碑条目将：

• 抛出异常

• 在尝试调用时显示清晰的错误消息

• 表明该插件已被移除

• 可能会引用替代插件

重定向 (Redirection)

插件重定向允许无缝地重命名或移动插件。当插件被重定向时：

• 旧插件名称会自动解析为新插件

• 不显示警告（除非目标插件也被弃用）

• 用户在迁移期间可以继续使用旧名称

• 重定向可以指向另一个集合中的插件

在集合中配置插件生命周期

集合通过位于 extensions/eda/eda_runtime.yml 的元数据文件来定义其中包含的插件生命周期。该文件使用 plugin_routing 部分来定义弃用、重定向和墓碑条目。

eda_runtime.yml 文件采用如下结构：

plugin_routing:
  event_source:
    plugin_name:
      # Lifecycle configuration here
  event_filter:
    plugin_name:
      # Lifecycle configuration here

弃用插件

要弃用插件，请添加一个包含移除信息和警告消息的 deprecation 条目。

事件源示例

plugin_routing:
  event_source:
    old_webhook:
      deprecation:
        removal_version: "2.0.0"
        warning_text: |
          Please migrate to the webhook_listener source which provides
          improved performance and additional features.

事件过滤器示例

plugin_routing:
  event_filter:
    legacy_filter:
      deprecation:
        removal_version: "3.0.0"
        warning_text: |
          Use the json_filter from eda.builtin for better
          JSON handling capabilities.

弃用字段

removal_version

插件将被移除时的集合版本。

removal_date

插件将被移除的 ISO 8601 日期 (YYYY-MM-DD)。

注意

必须指定 removal_version 或 removal_date 之中至少一个。如果两者都提供，将使用 removal_date。

warning_text (必填)

一条解释插件为何被弃用以及用户应使用什么替代方案的消息。

当用户运行使用被弃用插件的 rulebook 时，他们将看到类似如下的警告：

my_namespace.my_collection.old_webhook has been deprecated. The old_webhook
source is deprecated and will be removed in version 2.0.0. Please migrate to
the webhook_listener source which provides improved performance and additional
features. This feature will be removed from event source 'old_webhook' in
collection 'my_namespace.my_collection' version 2.0.0.

重定向插件

插件重定向允许您在保持向后兼容性的同时，重命名插件或将其移动到不同的集合中。

简单重定向/重命名

plugin_routing:
  event_source:
    old_name:
      redirect: my_namespace.my_collection.new_name

重定向目标必须是格式为 namespace.collection.plugin_name 的完全限定集合名称 (FQCN)。它可以指向当前集合或另一个集合中的插件。

带弃用提示的重定向

您可以将重定向与弃用警告相结合

plugin_routing:
  event_source:
    old_webhook:
      redirect: my_namespace.my_collection.webhook_listener
      deprecation:
        removal_version: "2.0.0"
        warning_text: |
          Please update your rulebooks to use the new plugin name.

此配置：

1. 将 old_webhook 重定向到 webhook_listener

2. 在使用旧名称时显示弃用警告

3. 在 2.0.0 版本之前继续有效

重定向链

Ansible-rulebook 会自动跟踪重定向链。如果插件 A 重定向到 B，而 B 重定向到 C，用户引用插件 A 时将最终解析为 C。

注意

ansible-rulebook 最多跟踪 10 次重定向

插件墓碑化 (Tombstoning)

在插件被移除后，在 eda_runtime.yml 中添加一个墓碑条目。这可以防止该插件被使用并提供清晰的错误消息

plugin_routing:
  event_source:
    removed_webhook:
      tombstone:
        removal_version: "2.0.0"
        warning_text: |
          Use webhook_listener instead.

墓碑字段

removal_version

插件被移除时的集合版本。

removal_date

插件被移除的 ISO 8601 日期 (YYYY-MM-DD)。

注意

必须指定 removal_version 或 removal_date 之中至少一个。如果两者都提供，将使用 removal_date。

warning_text (必填)

解释移除原因并建议替代方案的消息。

当用户尝试使用已墓碑化的插件时，ansible-rulebook 将抛出错误

SourcePluginNotFoundException: The my_namespace.my_collection.removed_webhook
event source has been removed. The removed_webhook source has been removed.
Use webhook_listener instead.

完整迁移示例

这是一个完整示例，展示了将事件源从 old_webhook 重命名为 webhook_listener 的生命周期

版本 1.5.0 - 引入带弃用提示的重定向

plugin_routing:
  event_source:
    old_webhook:
      redirect: my_namespace.my_collection.webhook_listener
      deprecation:
        removal_version: "2.0.0"
        warning_text: |
          The old_webhook source is deprecated and has been renamed
          to webhook_listener. Please update your rulebooks.

版本 2.0.0 - 替换为墓碑条目

plugin_routing:
  event_source:
    old_webhook:
      tombstone:
        removal_version: "2.0.0"
        warning_text: |
          The old_webhook source has been removed.
          Use webhook_listener instead.

技术细节

遗留映射 (Legacy Mappings)

Ansible-rulebook 维护内置的遗留映射，以向后兼容旧的插件名称。这些映射在 eda_runtime.yml 路由之前进行检查

# Event sources
ansible.eda.range → eda.builtin.range
ansible.eda.generic → eda.builtin.generic
ansible.eda.pg_listener → eda.builtin.pg_listener

# Event filters (partial list)
ansible.eda.json_filter → eda.builtin.json_filter
ansible.eda.normalize_keys → ansible.builtin.normalize_keys

操作顺序

在解析插件名称时，ansible-rulebook 遵循以下顺序：

1. 检查内置的遗留映射

2. 从插件的集合中加载 eda_runtime.yml

3. 检查是否弃用（如果存在则记录警告）

4. 检查是否为墓碑条目（如果存在则抛出错误）

5. 检查是否重定向（跟踪到新插件）

6. 对重定向链中的每个重定向重复步骤 2-5（最多 10 跳）

另请参阅

• Rulebook 与集合 - 集合结构与使用

• 事件源 - 事件源插件

• 事件过滤器 - 事件过滤器插件