如何平滑升级 Ansible 版本避免生产环境任务中断？

生产环境升级 Ansible 最稳妥的方式是在隔离环境中先验证兼容性，再通过版本锁定逐步灰度发布。

核心结论：升级动作本身不应直接在生产控制器系统 Python 中执行，需通过虚拟环境隔离并锁定 Collection 版本。

适用场景：生产环境定期维护、修复安全漏洞或需要新特性时
关键准备：独立测试环境、当前版本备份及回滚方案
验收标准：语法检查与 dry-run 通过后小范围灰度

环境备份与版本记录

升级前必须记录当前状态，以便出现问题时快速比对或回滚。

# 查看当前 Ansible 版本及 Python 路径
ansible `--version`

# 导出已安装的 Collection 列表
ansible-galaxy collection list > collections_backup.txt

# 记录当前 pip 包列表
pip freeze > pip_backup.txt

虚拟环境隔离与安装

避免污染系统 Python 环境，建议使用 venv 创建独立环境。注意 Ansible 6.0+ 版本结构变化，通常安装 ansible 包会自动依赖 ansible-core，无需单独安装 core 包。

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

# 激活环境
source ansible_venv/bin/activate

# 安装指定版本（示例为 6.5.0，请按需调整）
pip install ansible==6.5.0

# 验证新环境版本
ansible `--version`

依赖版本锁定配置

为防止 Collection 自动升级导致不一致，建议使用 requirements.yml 锁定版本。

# requirements.yml 示例
collections:
  - name: ansible.posix
    version: 1.5.0
  - name: community.general
    version: 6.5.0

# 安装锁定版本的 Collection
ansible-galaxy collection install -r requirements.yml

兼容性验证步骤

在测试环境或非核心节点执行以下检查，确保退出码为 0 且无严重警告。

# 语法检查
ansible-playbook site.yml `--syntax-check`

# 模拟运行（不变更目标状态）
ansible-playbook site.yml `--check` `--diff`

# 查看是否有 deprecated 警告
ansible-playbook site.yml `--check` 2>&1 | grep -i deprecated

异常回滚方案

如果升级后任务失败，立即执行回滚。

# 方案 A：切换回旧虚拟环境（推荐）
deactivate
source ansible_old_venv/bin/activate

# 方案 B：重新安装旧版本
pip install ansible==6.4.0 `--force-reinstall`

常见风险与排查

Python 解释器路径：升级后控制器 Python 版本变化，可能导致被管节点 ansible_python_interpreter 路径失效，需在 inventory 中确认。
配置文件优先级：确认 ansible.cfg 加载路径，避免环境变量 ANSIBLE_CONFIG 指向错误配置。
Collection 路径：新版本可能改变默认安装路径，检查 ~/.ansible/collections 或配置中的 COLLECTIONS_PATHS。