升级前务必在测试环境确认 playbook 中使用的模块是否已迁移至 Collection，并检查控制端 Python 版本是否满足要求。鉴于 Ansible 2.10 已停止维护，生产环境建议直接评估升级至 ansible-core 2.12+ 或更高 LTS 版本，以下变更说明仍适用于理解架构演进。
先说结论：这是一次架构调整较大的升级，核心变更在于内容分发机制从单体转向集合（Collections），直接生产升级风险较高。
- 适合：有完整测试环境、能接受调整模块引用路径的场景
- 先准备：备份当前环境并检查控制端 Python 版本不低于 3.5
- 验收：通过语法检查和干跑模式确认 playbook 无误后再切换
- 风险提示：2.10 版本已 EOL，存在安全漏洞不再修复，建议仅作过渡参考
版本选型建议
Ansible 2.10 是过渡版本，后续版本拆分为 ansible-core 和 ansible 包。若当前处于规划阶段，建议跳过 2.10，直接采用以下方案：
- 稳定推荐：ansible-core 2.12+ (LTS 支持)
- 最小要求：控制端 Python 3.8+ (新版要求更高)
- 旧版兼容：若必须升级 2.10，请确保仅用于内部隔离环境
命令速用版
# 检查当前版本及 Python 环境
ansible `--version`# 检查 Python 版本
python `--version`# 语法检查
ansible-playbook -i inventory playbook.yml `--syntax-check`# 干跑验证
ansible-playbook -i inventory playbook.yml `--check`核心变更与模块迁移
Ansible 2.10 将核心引擎与内容包分离。大量模块被移动到了独立的 Collection 中，原本直接调用的模块名可能失效，需要使用全限定集合名称（FQCN）。
常见模块 FQCN 对照表
| 原模块名 | 新 FQCN | 所属集合 |
|---|---|---|
| yum | ansible.builtin.yum | ansible.builtin |
| apt | ansible.builtin.apt | ansible.builtin |
| docker | community.general.docker | community.general |
| pip | ansible.builtin.pip | ansible.builtin |
| git | ansible.builtin.git | ansible.builtin |
自动化检测与批量修复
手动修改 playbook 效率低且易错，建议使用 ansible-lint 进行自动化检测和修复。
1. 安装 ansible-lint
pip install ansible-lint2. 检测废弃用法
ansible-lint playbook.yml观察输出中关于 fqcn 的警告，例如 fqcn[action-core] 提示需要使用内置集合名称。
3. 批量修复脚本示例
对于简单模块替换，可使用 sed 批量处理（需谨慎验证）：
# 示例：将 yum 模块引用替换为 FQCN
sed -i 's/^[[:space:]]*- yum:/ - ansible.builtin.yum:/g' playbook.yml验证与排查
执行语法检查命令，观察是否有 could not find module 报错。如果有，说明缺少对应的 collection 或模块名未更新。
使用 `--check` 模式运行 playbook，确认任务逻辑没有因版本差异出现意外行为。
若遇到 Collection not found 错误，请执行以下命令安装缺失集合：
ansible-galaxy collection install community.general常见坑
1. 隐式模块加载失败：升级后某些原本能直接用的模块报错找不到，这是因为它们被移到了 community 集合中，需要显式安装或更新引用。
2. 控制端与被管端混淆：Python 版本要求仅针对控制端。被管端（目标机器）仍然可以支持较旧的 Python 版本，具体取决于模块要求。
3. 插件路径变化：自定义的 callback 插件或 lookup 插件如果路径硬编码，可能因目录结构变化而失效。
4. 依赖冲突：升级 ansible 后，原有的 Python 依赖包可能不兼容，建议在虚拟环境中重新安装依赖。
原文链接：https://www.zjcp.cc/ask/11091.html