Ansible-core 2.20 迁移指南

本节讨论了 ansible-core 2.19 与 ansible-core 2.20 之间的行为变更。

旨在帮助您更新剧本 (playbooks)、插件以及 Ansible 基础架构的其他部分，以便它们能与此版本的 Ansible 协同工作。

请查阅本页以及 ansible-core 2.20 更新日志 (Changelog) 以了解必要的变更。

本文档是移植系列指南的一部分。完整的移植指南列表可以在 移植指南 中找到。

简介

无显著变更

剧本 (Playbook)

移除了 PowerShell 操作中的引号剥离

在执行复制和获取文件等 Windows 操作时，PowerShell 模块实用程序不再尝试从路径中去除引号。除非某个值被重复添加了引号，否则这不应影响正常的 Playbook。如果您的 Playbook 依赖于这种自动去引号功能，您需要调整路径格式。

引擎 (Engine)

无显著变更

插件 API

移除的功能

以下先前弃用的功能已被移除

  • DEFAULT_TRANSPORT 配置选项不再支持 smart 值，该值曾用于根据底层平台配置自动选择 ssh 或 paramiko 作为默认传输方式。

  • vault 和 unvault 过滤器不再接受已弃用的 vaultid 参数。

  • ansible-galaxy 命令不再支持 v2 Galaxy 服务器 API。托管集合的 Galaxy 服务器必须支持 v3。

  • dnf 和 dnf5 模块不再支持已弃用的 install_repoquery 选项。

  • encrypt 模块实用程序不再包含已弃用的 passlib_or_crypt API。

  • paramiko 连接插件不再支持先前已弃用的 PARAMIKO_HOST_KEY_AUTO_ADD 和 PARAMIKO_LOOK_FOR_KEYS 配置键。

  • py3compat.environ 调用已被移除。

  • 不继承自 BaseVarsPlugin 并定义了 get_vars 方法的变量插件，无法再使用已弃用的 get_host_vars 或 get_group_vars 回退机制。

  • yum_repository 模块不再支持已弃用的 keepcache 选项。

行为变更

  • DataLoader.get_basedir 方法现在返回绝对路径而非相对路径。依赖于相对路径的插件代码可能需要调整。

  • 参数规范验证现在将 None 值视为 str 类型的空字符串，以提高与 2.19 之前模板转换的一致性。

  • 当使用 failed_when 抑制错误时，结果中的 exception 键现已重命名为 failed_when_suppressed_exception。这可以防止错误在被抑制后由回调显示。如果您的 Playbook 检查结果中的异常，请按如下方式进行更新

# Before
- command: /bin/false
  register: result
  failed_when: false

- debug:
    msg: "Exception was: {{ result.exception }}"
  when: result.exception is defined

# After
- command: /bin/false
  register: result
  failed_when: false

- debug:
    msg: "Exception was: {{ result.failed_when_suppressed_exception }}"
  when: result.failed_when_suppressed_exception is defined

命令行

  • Python 3.11 不再是受支持的控制节点版本。运行 Ansible 现在需要 Python 3.12+。

  • Python 3.8 不再是受支持的远程版本。目标执行现在需要 Python 3.9+。

已废弃

INJECT_FACTS_AS_VARS

INJECT_FACTS_AS_VARS 配置目前的默认值为 True，但这已被弃用，并将在 Ansible 2.24 中切换为 False。

启用后，事实（facts）既可在 ansible_facts 字典中使用，也可作为主命名空间中的独立变量使用。在 ansible_facts 字典中，事实名称中的 ansible_ 前缀会被移除。

如果您正在访问“注入的”事实，您将收到弃用警告。为应对未来的默认设置：

更新您的 Playbook 以使用 ansible_facts 字典

# Deprecated - will stop working in 2.24
- debug:
    msg: "OS: {{ ansible_os_distribution }}"

# Recommended - works in all versions
- debug:
    msg: "OS: {{ ansible_facts['distribution'] }}"
    # Note: 'ansible_' prefix is removed inside ansible_facts

或者在您的配置中显式启用当前行为

在您的 ansible.cfg 文件中

[defaults]
inject_facts_as_vars = True

通过导出环境变量

export ANSIBLE_INJECT_FACT_VARS=True

其他弃用项

  • vars 内部变量缓存将在 2.24 中移除。此缓存曾用于内部，但会导致变量处于不一致状态。应改用 vars 和 varnames 查找。

  • 在 include_vars 模块中将 ignore_files 指定为字符串的做法已被弃用。请改用列表

# Deprecated
- include_vars:
    dir: vars/
    ignore_files: ".gitkeep"

# Correct
- include_vars:
    dir: vars/
    ignore_files: [".gitkeep"]

模块

已移除的模块

以下模块不再存在

  • 无显著变更

弃用通知

无显著变更

值得注意的模块变更

  • 如果 extensions 参数未指定为列表，include_vars 模块现在会报错。此前，非列表值会被静默接受。

  • 如果 ignore_files 参数未指定为列表，include_vars 模块现在会报错。此前，字符串值会被接受，但现在已被弃用。

  • replace 模块现在以 Unicode 字符的文本模式而非字节模式读取和写入文件，并将正则表达式匹配切换为 Unicode 字符而非字节。这可能会影响依赖字节级操作的 Playbook。

插件

值得注意的插件变更

无显著变更

迁移自定义脚本

无显著变更

网络

无显著变更