Ansible 模块或插件的生命周期

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

  1. 当模块或插件首次被 Ansible 接受时，我们认为它处于技术预览阶段，并在文档中进行标记。

  2. 如果模块或插件成熟，则会删除文档中的“预览”标记。这些模块和插件的向后兼容性得到维护，但不保证，这意味着它们的參數应保持稳定的含义。

  3. 如果模块或插件的目标 API 发生根本性变化，或者有人创建了其功能的更好实现，我们可能会将其标记为已弃用。已弃用的模块和插件仍然可用，但它们已接近生命周期结束。我们保留已弃用的模块和插件 4 个发布周期，并提供弃用警告，以帮助用户更新使用它们的 playbook 和角色。

  4. 当模块或插件已弃用四个发布周期后，它将被移除，并在路由配置中替换为墓碑条目。已移除的模块和插件不再与 Ansible 一起交付。墓碑条目可帮助用户查找替代模块和插件。

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

弃用 Ansible 主存储库中的模块和插件

要在 ansible-core 中弃用模块，您必须

  1. 重命名文件，使其以_开头，例如，将old_cloud.py重命名为_old_cloud.py。这使模块保持可用，并在模块索引页面上将其标记为已弃用。

  2. 在相关的更改日志中提及弃用（通过创建具有deprecated_features部分的更改日志片段）。

  3. 在相关的porting_guide_core_x.y.rst中引用弃用。

  4. 在文档中添加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:

告知用户应执行的操作，例如Use M(whatmoduletouseinstead) instead.。

弃用集合中的模块和插件

要在集合中弃用模块，您必须

  1. 在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 格式的日期，在此日期之后，模块将在集合的新主版本中移除。

  2. 在相关的更改日志中提及弃用。如果集合使用antsibull-changelog，请创建具有deprecated_features部分的更改日志片段。

  3. 在模块或插件的文档中添加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:

告知用户应执行的操作，例如Use M(whatmoduletouseinstead) instead.。有关引用除模块之外的其他实体的方法，请参阅模块文档中的链接。

更改 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条目。

集合中模块或插件的墓碑

要从集合中移除已弃用的模块或插件，您需要为其创建墓碑

  1. 移除模块或插件文件以及相关的文件，例如测试、文档引用和文档。

  2. 在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 格式的日期。日期应为下一个主版本的日期。