Ansible 核心版本升级后旧版 playbook 兼容性如何测试？

升级 Ansible 核心版本前，最稳妥的做法是在隔离环境中结合 ansible-lint 静态检查与 `--check` 模式干跑，确认无弃用警告后再小范围真机验证。

先说结论：兼容性测试不能只在生产环境直接尝试，需要建立分级验证机制，先静态扫描再动态干跑，最后真机灰度。

适合：Ansible Core 大版本升级或更换受控节点 Python 环境时
先准备：独立测试环境、ansible-lint 规则集、备份现有 playbook 及 vault 密码
验收：通过 `--check` 模式无报错且业务逻辑预期一致

测试环境快速搭建

不要直接覆盖生产环境的工具链，建议使用 virtualenv 隔离新版本。

# 创建虚拟环境
python3 -m venv ansible_new_env

# 激活环境
source ansible_new_env/bin/activate

# 安装指定版本 Ansible 及 lint 工具
pip install ansible-core==2.14.0 ansible-lint

命令速用版

# 检查 Ansible 版本
ansible `--version`

# 静态语法与最佳实践检查
ansible-lint playbooks/

# 干跑模式（不实际执行变更）
ansible-playbook -i inventory.ini site.yml `--check` -v

分步处理

1. 数据备份：备份当前 inventory 文件、vault 密码文件及 playbook 目录，防止配置丢失。

2. 静态扫描：运行 ansible-lint，修复所有 error 级别的提示，warning 级别需逐一确认是否涉及弃用功能。

3. 干跑验证：在测试 inventory 上使用 `--check` 模式运行，观察输出中是否有 DEPRECATION WARNING。

4. 单节点真测：挑选一台非关键业务主机，移除 `--check` 参数实际运行，确认系统状态符合预期。

5. 回滚准备：记录当前安装的版本号，一旦新版本验证失败可立即通过 pip 回退。

典型弃用警告修复案例

升级后常见报错涉及语法变更，例如旧版 with_items 循环建议改为 loop：

# 旧版写法（可能触发警告）
- name: Example
  debug:
    msg: "{{ item }}"
  with_items: "{{ my_list }}"

# 推荐写法
- name: Example
  debug:
    msg: "{{ item }}"
  loop: "{{ my_list }}"

怎么验证是否生效

检查命令执行后的返回码，0 表示成功。查看标准输出中是否有 DEPRECATION WARNING 或 ERROR。注意：`--check` 模式下 changed=1 不代表失败，仅表示若执行会产生变更，重点应关注 stderr 中是否有红色报错或弃用警告。

回滚操作指南

若新版本验证失败，可快速回退至旧版本：

# 退出虚拟环境（如需）
deactivate

# 重新安装旧版本
pip install ansible-core==2.13.0

常见坑

1. 集合路径变化：Ansible 2.10+ 引入 Collections 后，旧版模块调用路径可能失效，需检查 import 路径。

2. Jinja2 过滤器的行为变更：不同版本 Ansible 绑定的 Jinja2 版本可能不同，导致字符串处理结果差异。

3. 连接插件兼容性：ssh 参数或连接插件配置在新版本中可能被更严格校验，导致连接失败。

参考来源

Ansible Official Documentation - Porting Guides

URL: https://docs.ansible.com/ansible/latest/porting_guides/porting_guides.html