ansible-galaxy

安装与管理 Ansible 角色和集合

补充说明

ansible-galaxy 从 Galaxy 或私有源安装角色（role）和集合（collection），也用于初始化、构建和发布。集合是当前推荐的分发单位。

常用示例

ansible-galaxy collection install community.general
ansible-galaxy collection install -r requirements.yml
ansible-galaxy collection list
ansible-galaxy role install geerlingguy.nginx
ansible-galaxy role init myrole
ansible-galaxy collection init myns.mycol
ansible-galaxy collection build
ansible-galaxy collection publish myns-mycol-1.0.0.tar.gz
ansible-galaxy install -r requirements.yml -p ./roles

requirements.yml：

collections:
  - name: community.general
    version: ">=8.0.0,<9.0.0"
  - name: ansible.posix
    version: 1.5.4
roles:
  - name: geerlingguy.nginx
    version: 3.1.4

易错点与排错

• role 和 collection 是两套命名空间和安装路径；不要混为一谈。
• 版本不锁会拉到新版本；生产环境固定版本并提交 requirements。
• 集合安装路径必须包含 ansible_collections/<namespace>/<name>；手工放置容易找不到。
• 离线环境要提前下载 tarball 或用私有 Galaxy；install 默认联网。
• requirements.yml 的 collections/roles 段落格式不同；YAML 缩进错误会静默漏装。
• 私有集合需要 token 和源配置；不要把 token 写进 requirements。
• 角色依赖不会自动递归安装所有场景；执行前用 --list 或 dry-run 确认。
• 集合升级可能改变模块参数；升级后跑语法检查和小范围测试。

相关命令

• ansible-playbook — 使用角色和集合
• ansible-vault — 加密变量