Ansible 2.4 移植指南 

本节讨论 Ansible 2.3 和 Ansible 2.4 之间的行为变化。

旨在帮助您更新您的剧本、插件和 Ansible 基础架构的其他部分，以便它们能够与 Ansible 的此版本一起使用。

我们建议您阅读此页面以及 Ansible 2.4 的变更日志，以了解您可能需要进行哪些更新。

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

Python 版本 

Ansible 将不再支持目标主机上的 Python 2.4 或 2.5。展望未来，目标主机上将需要 Python 2.6+，就像控制器上一样。

清单 

清单已重构为通过插件实现，现在允许使用多个来源。此更改对用户来说大多是透明的。

一个例外是 inventory_dir，它现在是一个主机变量；以前它只能有一个值，因此它是全局设置的。这意味着您不能再在剧本的早期使用它来确定 hosts: 或类似的关键字。这也改变了 add_hosts 和隐式 localhost 的行为；因为它们不再自动继承全局值，所以它们默认为 None。有关更多信息，请参阅模块文档。

inventory_file 保持基本不变，因为它始终是特定于主机的。

由于不再存在单个清单，“隐式 localhost”不会定义这两个变量中的任何一个。

修复了清单路径/目录的一个错误，该错误默认为当前工作目录。这导致 group_vars 和 host_vars 从当前工作目录中获取，而不是仅在提供主机列表（逗号分隔的主机名）作为清单时从剧本或清单目录旁边获取。

初始剧本相关的 group_vars 和 host_vars 

在 2.4 之前的 Ansible 版本中，清单系统会维护执行的初始剧本的上下文。这允许从其他目录中连续包含的剧本继承相对于顶级剧本文件放置的 group_vars 和 host_vars。

由于某些行为不一致，此功能将不会包含在新清单系统中，从 Ansible 2.4 版本开始。

仍然可以通过使用 vars_files、include_vars 或相对于清单文件放置的 group_vars 和 host_vars 来实现类似的功能。

已弃用 

指定清单来源 

在命令行上使用 --inventory-file 现已弃用。使用 --inventory 或 -i。相关的 ini 配置键 hostfile 和环境变量 ANSIBLE_HOSTS 也已弃用。将它们替换为配置键 inventory 和环境变量 ANSIBLE_INVENTORY。

使用多个标签 

在命令行上多次指定 --tags（或 --skip-tags）目前会导致最后一个覆盖所有先前的标签。此行为已弃用。将来，如果您多次指定 –tags，则标签将合并在一起。从现在开始，在一条命令行上多次使用 --tags 将发出弃用警告。在 ansible.cfg 文件中将 merge_multiple_cli_tags 选项设置为 True 将启用新行为。

在 2.4 中，默认值已更改为合并标签。您可以通过配置选项启用旧的覆盖行为。

在 2.5 中，多个 --tags 选项将被合并，无法恢复到旧行为。

其他注意事项 

此版本没有重大更改。

模块 

此处详细说明了常用模块中的重大更改

win_shell 和 win_command 模块现在可以在命令行中正确保留带引号的参数。尝试通过添加额外的引号/转义来解决此问题的任务可能需要重新修改以删除多余的转义。有关更多详细信息，请参阅问题 23019。

已移除的模块 

以下模块不再存在

无

弃用通知 

以下模块将在 Ansible 2.8 中移除。请相应地更新您的剧本。

azure，使用 azure_rm_virtualmachine，它使用新的资源管理器 SDK。
win_msi，改用 win_package

值得注意的模块更改 

win_get_url 模块在其结果中弃用了字典 win_get_url，其内容现在也直接在结果输出中可用，就像其他模块一样。此字典将在 Ansible 2.8 中移除。
win_unzip 模块不再在其结果中包含字典 win_unzip；内容现在直接包含在结果输出中，就像其他模块一样。
win_package 模块的返回值 exit_code 和 restart_required 已弃用，建议使用 rc 和 reboot_required 替代。弃用的返回值将在 Ansible 2.6 中移除。

插件 

引入了一种配置和记录插件的新方法。这不需要更改现有的设置，但开发人员现在应该开始适应新的基础架构。更多详细信息将在每个插件类型的开发者文档中提供。

变量插件更改 

变量插件的实现发生了很多变化，但用户和开发人员都不需要更改任何内容来保持当前设置的正常工作。开发人员应该考虑更改其插件以利用新功能。

对用户来说最显著的区别是，变量插件现在按需调用，而不是在清单构建时调用。这应该使它们对于大型清单更有效率，尤其是在使用主机子集时。

注意

这在使用 playbook 旁边的 group/host_vars 时也会产生差异。之前，加载的“第一个”playbook 决定了变量；现在“当前”playbook 决定了变量。我们正在努力尽快解决这个问题，因为路径中的“所有 playbook”都应被考虑用于变量加载。
在 2.4.1 中，我们添加了一个切换开关来控制此行为，“top”将是 2.4 之前的版本，“bottom”将使用托管任务的当前 playbook，“all”将从上到下使用它们。

清单插件 

开发人员应该开始从使用动态清单脚本的硬编码清单迁移到新的清单插件。脚本仍然可以通过 script 清单插件工作，但 Ansible 的开发工作现在将集中在编写插件而不是增强现有脚本。

用户和开发人员都应该了解新的插件，因为它们旨在减少动态清单脚本中发现的许多 hack 和变通方法的需要。

回调插件 

用户

回调现在使用新的配置系统。用户不需要更改任何内容，因为旧系统仍然有效，但如果任何使用的回调没有从内置类继承，您可能会看到弃用通知。开发人员需要按照以下说明更新它们。

开发人员

如果您的回调没有从 CallbackBase（直接或间接地通过另一个回调）继承，它仍然可以工作，但会发出弃用通知。为避免这种情况并确保它在将来正常工作，请将其更改为从 CallbackBase 继承，以便它具有新的选项处理方法和属性。您还可以实现新的选项处理方法和属性，但这不会自动继承将来添加的更改。您可以查看 CallbackBase 本身和/或 AnsiblePlugin 以获取详细信息。
任何从其他回调继承的回调可能也需要更新，以包含与父回调相同的文档化选项，否则选项将不可用。这在开发者指南中有所说明。

模板查找插件：转义字符串 

在 Ansible 2.4 之前，传递给模板查找插件的字符串中的反斜杠会自动转义。在 2.4 中，用户负责自己转义反斜杠。此更改使模板查找插件与模板模块保持一致，以便相同的反斜杠转义规则适用于两者。

如果您有如下所示的模板查找

- debug:
    msg: '{{ lookup("template", "template.j2") }}'

**旧版本** 在 Ansible 2.3（及更早版本）中，template.j2 将如下所示

{{ "name surname" | regex_replace("^[^\s]+\s+(.*)", "\1") }}

**新版本** 在 Ansible 2.4 中，它应该更改为如下所示

{{ "name surname" | regex_replace("^[^\\s]+\\s+(.*)", "\\1") }}

测试 

测试成功/失败 

在 Ansible 2.4 版本之前，任务返回码 rc 将覆盖返回码 failed。在 2.4 版本中，rc 和 failed 都用于计算任务的状态。因此，测试插件 succeeded/failed` 也已更改。这意味着使用 failed_when: no 覆盖任务失败将导致 succeeded/failed 返回 True/False。例如

- command: /bin/false
  register: result
  failed_when: no

- debug:
    msg: 'This is printed on 2.3'
  when: result|failed

- debug:
    msg: 'This is printed on 2.4'
  when: result|succeeded

- debug:
    msg: 'This is always printed'
  when: result.rc != 0

从上面的示例可以看出，在 Ansible 2.3 中，succeeded/failed 只检查 rc 的值。

网络 

网络模块的操作方式发生了一些变化。

Playbook 仍应使用 connection: local。

持久连接 

在 Ansible 2.3 中添加的配置变量 connection_retries 和 connect_interval 现已弃用。对于 Ansible 2.4 及更高版本，请使用 connection_retry_timeout。

要控制超时，请使用 command_timeout 而不是之前在 [default] 下的顶级 timeout 变量。

有关更多信息，请参阅 Ansible 网络调试指南。

配置 

配置系统发生了一些重大更改。除了以下内容外，用户应该不受影响

定义的所有相对路径都相对于 ansible.cfg 文件本身。以前它们因设置而异。新行为应该更可预测。
一个新的宏 {{CWD}} 可用于路径，这将使路径相对于“当前工作目录”，这并不安全，但一些用户确实希望依赖此行为。

直接使用先前 API 的开发人员应重新审视其用法，因为某些方法（例如 get_config）是为了向后兼容而保留的，但会警告用户该函数已弃用。

新配置旨在最大程度地减少核心代码更改以支持新插件的需求。插件只需要记录其设置，配置系统将使用文档来提供它们所需的内容。这仍在进行中；目前只有“回调”和“连接”插件支持此功能。更多详细信息将添加到特定插件开发者指南中。