Ansible 2.8 移植指南

本节讨论 Ansible 2.7 和 Ansible 2.8 之间的行为变化。

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

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

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

剧本 

发行版信息 

返回的 ansible_distribution_* 组信息可能略有变化。Ansible 2.8 使用了一个新的后端库来获取有关发行版的信息：nir0s/distro。此库在 Python-3.8 上运行，并修复了许多错误，包括更正发行版和版本名称。

剧本中最常使用的两个信息，ansible_distribution 和 ansible_distribution_major_version，不应该发生变化。如果您发现这些信息发生了变化，请提交错误报告，以便我们解决差异。但是，其他信息，如 ansible_distribution_release 和 ansible_distribution_version，可能会发生变化，因为错误信息会被更正。

导入作为处理器 

从 2.8 版本开始，任务不能通知 import_tasks 或在 handlers 中指定的静态 include。

静态导入的目标是充当预处理器，其中导入会被导入文件中定义的任务替换。使用导入时，任务可以通知导入文件中任何命名的任务，但不能通知导入本身的名称。

为了实现通知单个名称但运行多个处理器的结果，请使用 include_tasks 或 listen 处理器：在更改时运行操作。

Jinja 未定义值 

从 2.8 版本开始，尝试访问 Jinja 中未定义值的属性将返回另一个未定义值，而不是立即抛出错误。这意味着您现在可以简单地在嵌套数据结构中使用带有值的默认值，而无需知道中间值是否已定义。

在 Ansible 2.8 中

{{ foo.bar.baz | default('DEFAULT') }}

在 Ansible 2.7 及更早版本中

{{ ((foo | default({})).bar | default({})).baz | default('DEFAULT') }}

或

{{ foo.bar.baz if (foo is defined and foo.bar is defined and foo.bar.baz is defined) else 'DEFAULT' }}

模块选项转换为字符串 

从 2.8 版本开始，如果模块期望一个字符串，但传递了一个非字符串值并自动转换为字符串，Ansible 将发出警告。这突出了潜在的问题，例如，yes 或 true（解析为真值布尔值）将转换为字符串 'True'，或者版本号 1.10（解析为浮点数）将转换为 '1.1'。根据上下文，此类转换可能导致意外行为。

可以通过设置 ANSIBLE_STRING_CONVERSION_ACTION 环境变量或在 ansible.cfg 的 defaults 部分设置 string_conversion_action 配置来更改此行为，使其成为错误或被忽略。

命令行信息 

cmdline 信息将在系统中被弃用，取而代之的是 proc_cmdline。此更改处理内核命令行参数包含多个具有相同键的值的特殊情况。

条件语句中的裸变量 

在 Ansible 2.7 及更早版本中，顶级变量有时会将布尔字符串视为布尔值。这导致基于定义为字符串的顶级变量构建的条件测试出现不一致的行为。Ansible 2.8 开始更改此行为。例如，如果您设置两个如下所示的条件

tasks:
  - include_tasks: teardown.yml
    when: teardown

  - include_tasks: provision.yml
    when: not teardown

基于您**作为字符串**定义的变量（在其周围加上引号）

在 Ansible 2.7 及更早版本中，如果 teardown: 'true'，则上述两个条件分别评估为 True 和 False。
在 Ansible 2.7 及更早版本中，如果 teardown: 'false'，则这两个条件都评估为 False。
在 Ansible 2.8 及更高版本中，您可以选择禁用条件裸变量，因此当 teardown 是非空字符串（包括 'true' 或 'false'）时，when: teardown 始终评估为 True，而 when: not teardown 始终评估为 False。

最终，when: 'string' 将始终评估为 True，而 when: not 'string' 将始终评估为 False，只要 'string' 不为空，即使 'string' 本身看起来像一个布尔值。对于依赖于旧行为的 playbook 用户，我们添加了一个配置设置来保留它。您可以使用 ANSIBLE_CONDITIONAL_BARE_VARS 环境变量或 conditional_bare_variables（位于 ansible.cfg 文件的 defaults 部分）来选择您在控制节点上所需的的行为。默认设置是 true，它保留了旧的行为。将配置值或环境变量设置为 false 以开始使用新选项。

注意

在 2.10 中，conditional_bare_variables 的默认设置将更改为 false。在 2.12 中，旧的行为将被弃用。

更新您的 playbook 

为了使您的 playbook 适应新行为，您必须更新您的条件语句，使其仅接受布尔值。对于变量，您可以使用 bool 过滤器将字符串 'false' 评估为 False

vars:
  teardown: 'false'

tasks:
  - include_tasks: teardown.yml
    when: teardown | bool

  - include_tasks: provision.yml
    when: not teardown | bool

或者，您可以将变量重新定义为布尔值（不带引号）而不是字符串。

vars:
  teardown: false

tasks:
  - include_tasks: teardown.yml
    when: teardown

  - include_tasks: provision.yml
    when: not teardown

对于字典和列表，使用 length 过滤器来评估字典或列表的存在性，将其视为 True。

- debug:
  when: my_list | length > 0

- debug:
  when: my_dictionary | length > 0

不要对列表或字典使用 bool 过滤器。如果您对列表或字典使用 bool，Ansible 将始终将其评估为 False。

双重插值 

conditional_bare_variables 设置也会影响基于其他变量设置的变量。旧的行为意外地对这些变量进行了双重插值。例如

vars:
  double_interpolated: 'bare_variable'
  bare_variable: false

tasks:
  - debug:
    when: double_interpolated

在 Ansible 2.7 及更早版本中，when: double_interpolated 评估为 bare_variable 的值，在本例中为 False。如果变量 bare_variable 未定义，则条件将失败。
在 Ansible 2.8 及更高版本中，禁用裸变量后，Ansible 将 double_interpolated 评估为字符串 'bare_variable'，该字符串为 True。

要进行双重插值变量值，请使用花括号。

vars:
  double_interpolated: "{{ other_variable }}"
  other_variable: false

嵌套变量 

conditional_bare_variables 设置不会影响嵌套变量。分配给子键的任何字符串值都已得到尊重，不会被视为布尔值。如果 complex_variable['subkey'] 是一个非空字符串，则 when: complex_variable['subkey'] 始终为 True，而 when: not complex_variable['subkey'] 始终为 False。如果您希望像 complex_variable['subkey'] 这样的字符串子键被评估为布尔值，则必须使用 bool 过滤器。

收集信息 

在 Ansible 2.8 中，play 中的隐式“收集信息”任务更改为遵守 play 标签。在 2.8 之前，“收集信息”任务会忽略 play 标签和从命令行提供的标签，并且始终在任务中运行。

行为更改会影响以下示例 play。

- name: Configure Webservers
  hosts: webserver
  tags:
    - webserver
  tasks:
    - name: Install nginx
      package:
        name: nginx
      tags:
        - nginx

在 Ansible 2.8 中，如果您提供 --tags nginx，则隐式“收集信息”任务将被跳过，因为该任务现在继承了 webserver 的标签，而不是 always。

如果未设置 play 级别标签，“收集信息”任务将被赋予 always 标签，并且会有效地匹配之前行为。

您可以通过在 tasks 列表中使用显式的 gather_facts 任务来获得与 2.8 之前版本类似的结果。

- name: Configure Webservers
  hosts: webserver
  gather_facts: false
  tags:
    - webserver
  tasks:
    - name: Gathering Facts
      gather_facts:
      tags:
        - always

    - name: Install nginx
      package:
        name: nginx
      tags:
        - nginx

Python 解释器发现 

在 Ansible 2.7 及更早版本中，Ansible 默认将 /usr/bin/python 作为 ansible_python_interpreter 的设置。如果您针对安装了不同名称或不同路径的 Python 的系统运行 Ansible，您的 playbook 将失败并显示 /usr/bin/python: bad interpreter: No such file or directory，除非您将 ansible_python_interpreter 设置为该系统的正确值，或者在 usr/bin/python 中添加了一个 Python 解释器和任何必要的依赖项。

从 Ansible 2.8 开始，Ansible 会在每个目标系统上搜索 Python 的正确路径和可执行文件名，首先在常见发行版的默认 Python 解释器查找表中搜索，然后在可能的 Python 解释器名称/路径的有序回退列表中搜索。

依赖于从回退列表中设置的 Python 解释器是有风险的，因为解释器可能会在将来的运行中发生更改。如果从回退列表中较高的位置安装了解释器（例如，作为安装其他包的副作用），则您原来的解释器及其依赖项将不再被使用。出于这个原因，当 Ansible 使用从回退列表中发现的 Python 解释器时，它会向您发出警告。如果您看到此警告，最佳解决方案是将 ansible_python_interpreter 显式设置为这些目标系统上正确解释器的路径。

您仍然可以在任何变量级别（作为主机变量、在 vars 文件中、在 playbook 中等）将 ansible_python_interpreter 设置为特定路径。如果您希望使用 Python 解释器发现行为，请使用 Ansible 2.8 中引入的四个新值之一来设置 ansible_python_interpreter。

新值	行为
auto （未来默认值）	如果发现了 Python 解释器，即使 /usr/bin/python 也存在，Ansible 也会使用发现的 Python。当使用回退列表时会发出警告。
auto_legacy （Ansible 2.8 默认值）	如果发现了 Python 解释器，并且 /usr/bin/python 不存在，Ansible 就会使用发现的 Python。当使用回退列表时会发出警告。如果发现了 Python 解释器，并且 /usr/bin/python 存在，Ansible 就会使用 /usr/bin/python，并打印有关未来默认行为的弃用警告。当使用回退列表时会发出警告。
auto_legacy_silent	行为类似于 `auto_legacy`，但会抑制弃用和回退列表警告。
auto_silent	行为类似于 `auto`，但会抑制回退列表警告。

在 Ansible 2.12 中，Ansible 将默认值从 auto_legacy 更改为 auto。行为上的差异在于 auto_legacy 会在存在时使用 /usr/bin/python，而在不存在时回退到发现的 Python。 auto 将始终使用发现的 Python，无论 /usr/bin/python 是否存在。 auto_legacy 设置提供了与以前版本的 Ansible 的兼容性，这些版本始终默认使用 /usr/bin/python。

如果您将 Python 和依赖项（boto 等）安装到 /usr/bin/python 作为在具有不同默认 Python 解释器（例如，Ubuntu 16.04+、RHEL8、Fedora 23+）的发行版上的解决方法，您有两个选择。

将现有的依赖项移动到每个平台/发行版/版本的默认 Python。

使用 auto_legacy。此设置允许 Ansible 在具有该设置的主机上查找并使用解决方法 Python，同时还在较新的主机上查找正确的默认 Python。但请记住，默认设置将在 4 个版本后更改。

重试文件创建默认值 

在 Ansible 2.8 中，retry_files_enabled 现在默认为 False，而不是 True。可以通过编辑默认的 ansible.cfg 文件并将值设置为 True 来修改行为，使其恢复到之前的版本。

命令行 

提升权限提示 

从 2.8 版本开始，默认情况下，Ansible 将使用单词 BECOME 提示您输入提升权限的密码（Unix 系统上的 sudo 权限或网络设备上的 enable 模式）。

Ansible 2.8 中的默认设置

ansible-playbook --become --ask-become-pass site.yml
BECOME password:

如果您希望提示显示正在使用的特定 become_method，而不是通用值 BECOME，请在 Ansible 配置文件中将 AGNOSTIC_BECOME_PROMPT 设置为 False。

Ansible 2.7 中的默认设置，或 Ansible 2.8 中使用 AGNOSTIC_BECOME_PROMPT=False 时

ansible-playbook --become --ask-become-pass site.yml
SUDO password:

已弃用 

使用任务/剧本环境键 ANSIBLE_ASYNC_DIR 设置异步目录已弃用，将在 Ansible 2.12 中移除。您可以通过将 ansible_async_dir 作为变量设置来达到相同的效果，例如：
```
- name: run task with custom async directory
  command: sleep 5
  async: 10
  vars:
    ansible_async_dir: /tmp/.ansible_async
```
需要 FactCache 对象的插件编写者应该注意两个弃用事项
1. FactCache 类已从 ansible.plugins.cache.FactCache 移动到 ansible.vars.fact_cache.FactCache。这是因为 FactCache 不是缓存插件 API 的一部分，缓存插件作者不应该对其进行子类化。 FactCache 仍然可以通过其旧位置访问，但当从该位置使用时会发出弃用警告。旧位置将在 Ansible 2.12 中移除。
2. FactCache.update() 方法已转换为遵循字典 API。它现在以字典作为其唯一参数，并用字典的项更新自身。以前的 API（其中 update() 接受键和值）现在将发出弃用警告，并将在 2.12 中移除。如果您需要旧的行为，请改用 FactCache.first_order_merge()。
通过 self.cache 支持基于文件的缓存已弃用，并将 Ansible 2.12 中移除。如果您维护一个清单插件，请将其更新为使用 self._cache 作为字典。有关实现细节，请参阅清单插件开发者指南。
直接导入缓存插件已弃用，并将 Ansible 2.12 中移除。使用 plugin_loader，以便可以使用配置系统而不是常量来协调直接选项、环境变量和其他配置方法。
```
from ansible.plugins.loader import cache_loader
cache = cache_loader.get('redis', **kwargs)
```

模块 

此处详细介绍了常用模块中的主要更改

运行 PowerShell 模块的 exec 包装器已更改为全局设置 $ErrorActionPreference = "Stop"。这可能意味着如果自定义模块隐式依赖此行为，则可能会失败。要恢复旧的行为，请在模块顶部添加 $ErrorActionPreference = "Continue"。进行此更改是为了恢复 EAP 的旧行为（在之前的版本中意外删除），并确保模块对执行过程中可能发生的错误更具弹性。

Ansible 的 2.8.14 版本将基于文件的任务的默认模式更改为 0o600 & ~umask，前提是用户未在基于文件的任务上指定 mode 参数。这是针对 CVE 报告做出的回应，但我们重新考虑了该问题。因此，在 2.8.15 中已恢复了 mode 更改，并且 mode 现在将默认为 0o666 & ~umask，与 Ansible 的先前版本相同。
如果您在使用 2.8.14 时更改了任何任务以指定权限较低的权限，则在 2.8.15 中这些更改将不再需要（但不会造成任何损害）。
为了避免 CVE-2020-1736 中提出的问题，请在所有接受它的基于文件的任务中指定 mode 参数。
dnf 和 yum - 从 2.8.15 版本开始，dnf 模块（以及当它使用 dnf 时的 yum 操作）现在可以正确验证软件包的 GPG 签名 (CVE-2020-14365)。如果您看到类似 Failed to validate GPG signature for [package name] 的错误，请确保您已为正在使用的 DNF 存储库和/或软件包导入了正确的 GPG 密钥。一种方法是使用 rpm_key 模块。尽管我们不鼓励这样做，但在某些情况下可能需要禁用 GPG 检查。这可以通过在 dnf 或 yum 任务中显式添加 disable_gpg_check: yes 来完成。

已移除的模块 

以下模块不再存在

ec2_remote_facts
azure
cs_nic
netscaler
win_msi

弃用通知 

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

foreman 请改用 foreman-ansible-modules。
katello 请改用 foreman-ansible-modules。
github_hooks 请改用 github_webhook 和 github_webhook_facts。
digital_ocean 请改用 digital_ocean_droplet。
gce 请改用 gcp_compute_instance。
gcspanner 请改用 gcp_spanner_instance 和 gcp_spanner_database。
gcdns_record 请改用 gcp_dns_resource_record_set。
gcdns_zone 请改用 gcp_dns_managed_zone。
gcp_forwarding_rule 请改用 gcp_compute_global_forwarding_rule 或 gcp_compute_forwarding_rule。
gcp_healthcheck 请改用 gcp_compute_health_check、gcp_compute_http_health_check 或 gcp_compute_https_health_check。
gcp_backend_service 请改用 gcp_compute_backend_service。
gcp_target_proxy 请改用 gcp_compute_target_http_proxy。
gcp_url_map 请改用 gcp_compute_url_map。
panos 请改用 Palo Alto Networks Ansible Galaxy 角色。

值得注意的模块更改 

foreman 和 katello 模块已被弃用，取而代之的是一组按实体分解的模块，这些模块更注重幂等性。
foreman 和 katello 模块的替代方案正式成为 Foreman 社区的组成部分，并得到那里的支持。
tower_credential 模块最初要求 ssh_key_data 是 ssh_key_file 的路径。为了与 AWX/Tower/RHAAP 保持一致，ssh_key_data 现在包含文件的内容。可以通过 lookup('file', '/path/to/file') 来实现之前的行为。
win_scheduled_task 模块已弃用将触发器重复指定为列表的方式，此格式将在 Ansible 2.12 中移除。请改用字典值指定重复。
win_feature 模块已移除弃用的 restart_needed 返回值，请改用标准化的 reboot_required 值。
win_package 模块已移除弃用的 restart_required 和 exit_code 返回值，请改用标准化的 reboot_required 和 rc 值。
win_get_url 模块已移除弃用的 win_get_url 返回字典，包含的值将直接返回。
win_get_url 模块已移除弃用的 skip_certificate_validation 选项，请改用标准化的 validate_certs 选项。
vmware_local_role_facts 模块现在返回一个字典列表，而不是字典的字典，用于表示角色信息。
如果 docker_network 或 docker_volume 使用 diff: yes、check_mode: yes 或 debug: yes 调用，则会返回一个名为 diff 的返回值，类型为 list。为了启用正确的差异输出，此类型已更改为 dict；原始的 list 作为 diff.differences 返回。
na_ontap_cluster_peer 模块已将 source_intercluster_lif 和 dest_intercluster_lif 字符串选项替换为 source_intercluster_lifs 和 dest_intercluster_lifs 列表选项。
modprobe 模块现在可以检测内核内置模块。以前，尝试移除（使用 state: absent）内置内核模块会成功，没有任何错误消息，因为 modprobe 没有检测到该模块为 present。现在，如果内核模块是内置的并且 state: absent，则 modprobe 将失败（并显示来自 modprobe 二进制文件的错误消息，例如 modprobe: ERROR: Module nfs is builtin.），如果 state: present，则会成功且不会报告更改。任何使用 changed_when: no 来掩盖此问题的 playbook 可以安全地移除该解决方法。要获得在将 state: absent 应用于内置内核模块时之前的行为，请在 playbook 中使用 failed_when: false 或 ignore_errors: true。
digital_ocean 模块已被弃用，建议使用不需要外部依赖项的模块。这可以提高灵活性并更好地支持模块。
docker_container 模块已弃用返回的事实 docker_container。相同的值可作为返回的变量 container 获取。返回的事实将在 Ansible 2.12 中移除。
docker_network 模块已弃用返回的事实 docker_container。相同的值可作为返回的变量 network 获取。返回的事实将在 Ansible 2.12 中移除。
docker_volume 模块已弃用返回的事实 docker_container。相同的值可作为返回的变量 volume 获取。返回的事实将在 Ansible 2.12 中移除。
docker_service 模块已重命名为 docker_compose。
重命名的 docker_compose 模块过去会为每个服务返回一个事实，其名称与服务相同。这些事实的字典作为常规返回值 services 返回。返回的事实将在 Ansible 2.12 中移除。
docker_swarm_service 模块不再为以下选项设置默认值。
- user。以前，默认值为 root。
- update_delay。以前，默认值为 10。
- update_parallelism。以前，默认值为 1。
vmware_vm_facts 过去会返回包含虚拟机信息的字典的字典。Ansible 2.8 及更高版本将返回包含虚拟机信息的字典列表。请参阅模块 vmware_vm_facts 文档以获取示例。
vmware_guest_snapshot 模块过去会返回 results。由于 Ansible 2.8 及更高版本 results 是一个保留关键字，因此已将其替换为 snapshot_results。请参阅模块 vmware_guest_snapshots 文档以获取示例。
panos 模块已被弃用，建议使用 Palo Alto Networks 的 Ansible Galaxy 角色。可以在此贡献角色。
ipa_user 模块最初始终将 password 发送到 FreeIPA，无论密码是否更改。现在，该模块仅在 update_password 设置为 always 时发送 password，这是默认设置。
win_psexec 已弃用未公开记录的 extra_opts 模块选项。此选项将在 Ansible 2.10 中移除。
win_nssm 模块已弃用以下选项，建议改用 win_service 模块在使用 win_nssm 安装服务后配置服务：* dependencies，请改用 win_service 的 dependencies * start_mode，请改用 win_service 的 start_mode * user，请改用 win_service 的 username * password，请改用 win_service 的 password 这些选项将在 Ansible 2.12 中移除。
win_nssm 模块还弃用了 status 选项的 start、stop 和 restart 值。您应该使用 win_service 模块来控制服务的运行状态。此功能将在 Ansible 2.12 中移除。
针对 win_nssm 模块的 status 选项，其默认值已从 start 变更为 present。因此，使用 win_nssm 创建服务后，服务不再默认启动，如果需要启动服务，则应使用 win_service 模块。
针对 win_nssm 模块的 app_parameters 选项已弃用，请使用 argument 替代。此选项将在 Ansible 2.12 中移除。
针对 win_nssm 模块的 app_parameters_free_form 选项已别名为新的 arguments 选项。
win_dsc 模块现在将验证 DSC 资源的输入选项。在以前的版本中，无效选项会被忽略，但现在不会。
openssl_pkcs12 模块现在会在磁盘上的文件与传递给模块的参数之间存在差异时重新生成 pkcs12 文件。

插件 

当使用 macOS 作为控制节点时，Ansible 不再默认使用 paramiko 连接插件。Ansible 现在将在 macOS 控制节点上默认使用 ssh 连接插件。由于 ssh 支持任务和 playbook 运行之间的连接持久性，因此它的性能优于 paramiko。如果使用密码认证，则在使用 ssh 连接插件时需要安装 sshpass。或者，可以显式地将连接类型设置为 paramiko 以保持 macOS 上 2.8 之前的行为。
连接插件已标准化，允许使用 ansible_<conn-type>_user 和 ansible_<conn-type>_password 变量。诸如 ansible_<conn-type>_pass 和 ansible_<conn-type>_username 之类的变量的优先级低于标准化名称，将来可能会弃用。通常，除非有理由使用特定于连接的变量，否则应使用 ansible_user 和 ansible_password 变量。
powershell shell 插件现在使用 async_dir 定义结果文件的异步路径，默认值已更改为 %USERPROFILE%\.ansible_async。要控制此路径，请设置 ansible_async_dir 变量或配置文件中 powershell 部分的 async_dir 值。
已更新启用的清单插件的顺序（INVENTORY_ENABLED），auto 现在位于 yaml 和 ini 之前。
已从回调插件的 CallbackBase 类中删除了私有 _options 属性。如果您的第三方回调插件需要访问命令行参数，请使用以下代码代替尝试使用 self._options
```
from ansible import context
[...]
tags = context.CLIARGS['tags']
```
context.CLIARGS 是一个只读字典，因此正常的字典检索方法（如 CLIARGS.get('tags') 和 CLIARGS['tags']）按预期工作，但您将无法修改 cli 参数。
Play 回顾现在计算 ignored 和 rescued 任务，以及 ok、changed、unreachable、failed 和 skipped 任务，这要归功于 default 回调插件中的两个额外的统计计数器。失败并设置了 ignore_errors: yes 的任务将列为 ignored。失败然后执行救援部分的任务将列为 rescued。请注意，rescued 任务不再像 Ansible 2.7（及更早版本）那样计为 failed。
osx_say 回调插件已重命名为 say。
清单插件现在通过缓存插件支持缓存。要开始使用清单的缓存插件，请参阅清单指南中关于缓存的部分。要移植自定义缓存插件以使其与清单兼容，请参阅关于缓存插件的开发者指南。

移植自定义脚本 

显示类 

从 Ansible 2.8 开始，Display 类现在是“单例”。每个文件都应该自己导入和实例化 ansible.utils.display.Display，而不是使用 __main__.display。

**旧版** 在 Ansible 2.7（及更早版本）中，使用以下方法访问 display 对象

try:
    from __main__ import display
except ImportError:
    from ansible.utils.display import Display
    display = Display()

**新版** 在 Ansible 2.8 中，应使用以下方法

from ansible.utils.display import Display
display = Display()

网络 

eos_config、ios_config 和 nxos_config 模块已删除弃用的 save 和 force 参数，请使用 save_when 参数来复制其功能。
nxos_vrf_af 模块已删除 safi 参数。此参数在 Ansible 2.4 中已弃用，并且从那时起对模块没有影响。