升级 Ansible 后 collection 路径变更导致模块找不到怎么配置

升级 Ansible 2.10 及以上版本后，模块找不到通常是因为默认搜索路径变更或未安装对应的 Collection。最推荐的处理方向是检查 ansible.cfg 中的 collections_paths 配置，并使用 ansible-galaxy 安装缺失的集合。

先说结论：升级后模块丢失主要是 Ansible 2.10 引入 Collection 架构导致的路径和命名空间变化，需重新配置路径或安装集合。

先确认：使用 ansible-config 查看当前生效的 COLLECTIONS_PATHS。
先处理：通过 ansible-galaxy 安装缺失的 community 或自定义集合。
再验证：运行 ansible-config dump 确认路径包含预期目录，并测试模块调用。

命令速用版

以下是快速查看配置和安装集合的命令，适用于大多数 Linux 环境。

# 查看当前生效的 collection 路径
ansible-config dump | grep COLLECTIONS_PATHS

# 安装常用的 community 集合
ansible-galaxy collection install community.general

# 临时指定路径运行（测试用）
ANSIBLE_COLLECTIONS_PATHS=/opt/ansible/collections ansible-playbook site.yml

为什么会这样

Ansible 2.10 版本开始将核心模块拆分为 Collection 结构，导致默认加载路径和模块命名规则发生变化。

在 Ansible 2.9 及之前，模块直接位于 lib/ansible/modules 下，升级至 2.10+ 后，大量模块迁移至独立的 Collection 包中。如果升级过程中未同步安装这些集合，或者自定义的 COLLECTIONS_PATHS 未被 ansible.cfg 正确读取，Ansible 就无法在默认路径中找到模块文件，从而报错“模块找不到”。

分步处理

按顺序执行以下步骤，修复路径配置并恢复模块可用性。

步骤 1：检查当前配置路径

运行配置查看命令，确认 Ansible 实际读取的 paths 列表。

ansible-config dump | grep COLLECTIONS_PATHS

检查输出是否包含你存放集合的目录，默认通常包含 ~/.ansible/collections 和 /usr/share/ansible/collections。

步骤 2：修改 ansible.cfg 配置

如果默认路径不符合需求，在项目根目录或/etc/ansible/ansible.cfg 中修改 [defaults] 段落。

[defaults]
collections_paths = ~/.ansible/collections:/usr/share/ansible/collections:/opt/custom/collections

步骤 3：安装缺失的集合

根据报错信息中缺失的模块名，推断所属集合并安装。例如 missing module 'xyz' in collection 'community.general'。

ansible-galaxy collection install community.general

步骤 4：更新 Playbook 中的模块引用

Ansible 2.10+ 推荐使用 FQCN（完全限定集合名称）。将旧写法 module: yum 改为 community.general.yum 或 ansible.builtin.yum。

怎么验证是否生效

完成配置后，通过以下两种方式确认修复结果。

1. 配置验证

再次运行 ansible-config dump，确认 COLLECTIONS_PATHS 显示的路径与你配置的一致，且没有报错。

2. 模块调用测试

使用 ansible 命令直接调用之前报错的模块，观察是否返回成功状态。

ansible localhost -m community.general.ping

如果返回 SUCCESS 且无 module not found 错误，说明路径配置和集合安装已生效。

常见坑

虚拟环境隔离：如果使用 pip 在 virtualenv 中安装 Ansible，集合默认安装在虚拟环境内，系统级 ansible.cfg 可能无法读取。
权限问题：/usr/share/ansible/collections 目录通常需要 root 权限写入，普通用户建议配置到家目录。
内置模块变更：部分原核心模块已移至 ansible.builtin 命名空间，旧 playbook 需更新引用。

常见问题

升级后默认 collection 路径在哪里？

默认路径通常包括 ~/.ansible/collections 和 /usr/share/ansible/collections，具体以 ansible-config dump 输出为准。

如何知道缺失的模块属于哪个 collection？

查看报错信息通常会提示模块所属集合，或在 Ansible 文档官网搜索模块名查看所属 namespace。

ansible.cfg 配置不生效怎么办？

检查配置文件位置优先级，当前目录下的 ansible.cfg 优先级高于家目录和系统目录，确认编辑的是生效的那个文件。

参考来源

Ansible Documentation, "Installing collections", https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html
Ansible Documentation, "Configuration Settings", https://docs.ansible.com/ansible/latest/reference_appendices/config.html