Ansible 模块或插件的生命周期

主 Ansible 仓库中的模块和插件具有定义的生命周期，从首次引入到最终移除。模块和插件的生命周期与 Ansible 发布周期 <release_cycle> 相关。一个模块或插件可能会经历以下四个阶段：

当一个模块或插件首次被接受到 Ansible 中时，我们认为它处于技术预览阶段，并会在文档中将其标记为预览。
如果一个模块或插件成熟了，文档中的“预览”标记将被删除。这些模块和插件的向后兼容性会被维护，但不保证，这意味着它们的参数应该保持稳定的含义。
如果一个模块或插件的目标 API 发生根本性变化，或者如果有人创建了更好的功能实现，我们可能会将其标记为已弃用。已弃用的模块和插件仍然可用，但它们正在接近生命周期的终点。我们保留已弃用的模块和插件 4 个发布周期，并提供弃用警告，以帮助用户更新使用它们的 Playbook 和角色。
当一个模块或插件被弃用 4 个发布周期后，它将被删除，并在路由配置中替换为墓碑条目。被删除的模块和插件不再随 Ansible 一起发布。墓碑条目可以帮助用户找到替代的模块和插件。

对于集合中的模块和插件，生命周期类似。自从 ansible-base 2.10 以来，不再可以将模块标记为“预览”或“稳定”。

在 Ansible 主仓库中弃用模块和插件

要在 ansible-core 中弃用一个模块，你必须：

重命名文件，使其以 _ 开头，例如，将 old_cloud.py 重命名为 _old_cloud.py。这会使模块保持可用，并在模块索引页面上将其标记为已弃用。
在相关的变更日志中提及弃用（通过创建一个带有 deprecated_features 部分的变更日志片段）。
在相关的 porting_guide_core_x.y.rst 中引用弃用。
将 deprecated: 添加到文档中，并使用以下子值：

removed_in:

一个 string，例如 "2.10"；Ansible 的版本，在该版本中，该模块将替换为仅包含文档的模块存根。通常是当前版本 +4。与 :removed_by_date: 互斥。

remove_by_date:

（在 ansible-base 2.10 中添加）。模块将被删除的 ISO 8601 格式日期。通常是从模块被弃用之日起 2 年。与 :removed_in: 互斥。

why:

可选字符串，用于详细说明为何删除此项。

alternatives:

告知用户他们应该做什么，例如，使用 M(whatmoduletouseinstead) 代替。。

有关记录弃用的示例，请参阅这个弃用多个模块的 PR。PR 中的某些元素现在可能已过期。

在集合中弃用模块和插件

要在集合中弃用一个模块，你必须：

在 meta/runtime.yml 中的 plugin_routing 中添加一个 deprecation 条目。例如，要弃用模块 old_cloud，请添加：
```
plugin_routing:
    modules:
        old_cloud:
            deprecation:
                removal_version: 2.0.0
                warning_text: Use foo.bar.new_cloud instead.
```
对于其他插件类型，你必须将 modules: 替换为 <plugin_type>:，例如查找插件的 lookup:。在弃用操作插件时，你需要添加两个条目：一个用于操作插件，另一个用于包含文档的模块文件。

除了 removal_version，你还可以使用 removal_date，其中包含 ISO 8601 格式的日期，在该日期之后，该模块将在集合的新主要版本中被删除。
在相关的变更日志中提及弃用。如果集合使用 antsibull-changelog，则创建一个带有 deprecated_features 部分的变更日志片段。
将 deprecated: 添加到模块或插件的文档中，并使用以下子值：

removed_in:

一个 string，例如 "2.10"；Ansible 的版本，在该版本中，该模块将替换为仅包含文档的模块存根。通常是当前版本 +4。与 :removed_by_date: 互斥。

remove_by_date:

（在 ansible-base 2.10 中添加）。模块将被删除的 ISO 8601 格式日期。通常是从模块被弃用之日起 2 年。与 :removed_in: 互斥。

why:

用于详细说明为何删除此项的字符串。

alternative:

告知用户他们应该做什么，例如，使用 M(whatmoduletouseinstead) 代替。。有关引用模块以外的实体的方式，请参阅模块文档中的链接。

在 Ansible 主仓库中更改模块或插件名称

你还可以重命名模块，并通过使用以 _ 开头的符号链接来保留对旧名称的已弃用别名。此示例允许使用 fileinfo 调用 stat 模块，使以下示例等效：

ln -s stat.py _fileinfo.py
ansible -m stat -a "path=/tmp" localhost
ansible -m fileinfo -a "path=/tmp" localhost

在集合中重命名模块或插件，或将模块或插件重定向到另一个集合

要在集合中重命名模块或插件，或将模块或插件重定向到另一个集合，你需要在 meta/runtime.yml 中的 plugin_routing 中添加一个 redirect 条目。例如，要将模块 old_cloud 重定向到 foo.bar.new_cloud，请添加：

plugin_routing:
    modules:
        old_cloud:
            redirect: foo.bar.new_cloud

如果要弃用旧名称，请添加一个 deprecation: 条目（见上文）。

plugin_routing:
    modules:
        old_cloud:
            redirect: foo.bar.new_cloud
            deprecation:
                removal_version: 2.0.0
                warning_text: Use foo.bar.new_cloud instead.

你需要使用新模块/插件名称的完全限定集合名称 (FQCN)，即使它与重定向位于同一集合中。通过使用来自另一个集合的 FQCN，你可以将模块/插件重定向到该集合。

如果你需要支持 Ansible 2.9，请注意 Ansible 2.9 不知道 meta/runtime.yml。使用 Ansible 2.9，你仍然可以使用符号链接在同一个集合中重命名插件和模块。请注意，ansible-base 2.10、ansible-core 2.11 及更高版本将优先选择 meta/runtime.yml 条目，而不是符号链接。

在集合中标记模块或插件为墓碑

要从集合中删除已弃用的模块或插件，你需要将其标记为墓碑。

删除模块或插件文件，以及相关的文件，如测试、文档参考和文档。
在 meta/runtime.yml 中添加一个墓碑条目。例如，要将模块 old_cloud 标记为墓碑，请添加：
```
plugin_routing:
    modules:
        old_cloud:
            tombstone:
                removal_version: 2.0.0
                warning_text: Use foo.bar.new_cloud instead.
```
除了 removal_version，您还可以使用 removal_date，并使用 ISO 8601 格式化的日期。该日期应该是下一个主要版本的发布日期。