基础设施即代码 / 系统课时
使用 Collections 组织内容
使用 Collections 组织内容
当角色、模块和插件开始跨项目复用时,仅靠目录名很容易发生重名和引用漂移。本课把这些内容收进 namespace.collection 命名空间,并用 FQCN 明确引用来源,最终得到一个可本地运行、可继续打包发布的 Collection 骨架。
学习目标
- 说清 Collection、namespace 与 FQCN 的关系。
- 创建包含 Role 的最小 Collection,并从 Playbook 中稳定引用。
- 判断何时应使用 FQCN,以及 Collection 在仓库中的合理边界。
用命名空间建立稳定边界
Collection 的完整名称由两段组成:namespace.collection。例如 acme.platform 中,acme 通常代表组织或团队,platform 表示一组同领域自动化内容。Collection 内可以同时放置 Roles、Modules、Filter、Lookup 等插件,也可以携带文档与元数据。
FQCN 则把“内容属于谁”写进引用本身。内置模块写成 ansible.builtin.debug,自定义 Role 可以写成 acme.platform.banner。相比依赖短名称搜索路径,FQCN 更不容易被同名插件覆盖,也让代码审查者无需猜测内容来源。

创建并运行最小 Collection
下面的命令创建 acme.platform,再加入一个 banner Role 和测试 Playbook。示例使用独立实验目录,不依赖系统级 Collection 安装路径。
WORKDIR="$HOME/anystack-ansible-collections-lab"
rm -rf "$WORKDIR"
mkdir -p "$WORKDIR/collections/ansible_collections"
ansible-galaxy collection init acme.platform \
--init-path "$WORKDIR/collections/ansible_collections"
mkdir -p "$WORKDIR/collections/ansible_collections/acme/platform/roles/banner/tasks"
cat > "$WORKDIR/collections/ansible_collections/acme/platform/roles/banner/tasks/main.yml" <<'YAML'
---
- name: Print collection role marker
ansible.builtin.debug:
msg: "role from acme.platform"
YAML
cat > "$WORKDIR/ansible.cfg" <<'CFG'
[defaults]
collections_path = ./collections
CFG
cat > "$WORKDIR/playbook.yml" <<'YAML'
---
- name: Verify collection role
hosts: localhost
gather_facts: false
roles:
- role: acme.platform.banner
YAML
cd "$WORKDIR"
ansible-playbook -i localhost, -c local playbook.yml预期输出中会看到 Role 的 FQCN 和自定义消息;Ansible 版本不同会使任务计数和格式略有差异。
TASK [acme.platform.banner : Print collection role marker] ***
ok: [localhost] => {
"msg": "role from acme.platform"
}
PLAY RECAP ***
localhost : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0这里的关键不是目录本身,而是 ansible.cfg 把当前项目的 ./collections 加入搜索路径后,Playbook 可以直接解析 acme.platform.banner。以后把同一 Collection 安装到标准 Collection 路径,调用方式无需改变。
按内容类型放进固定目录
Role 放在 roles/<role_name>/;模块通常放在 plugins/modules/;过滤器放在 plugins/filter/。Collection 根目录中的 galaxy.yml 描述名称、版本、作者等发布元数据。插件文件名与 Role 名只负责 Collection 内部定位,真正跨仓库使用时应以 FQCN 作为稳定接口。
如果一个 Collection 同时塞入数据库、中间件、网络和云资源等彼此无关的内容,命名空间虽然统一,维护边界却会变差。更合适的做法是按可独立版本化、可独立测试和可独立发布的领域拆分 Collection。
FQCN 与 collections 关键字的取舍
Playbook 可以使用 collections 关键字影响短名称解析,但它会把依赖关系隐藏在上下文中。对共享代码、长期维护的 Role 和插件,优先直接写 FQCN;短名称更适合非常局部、来源毫无歧义的场景。
真正值得放进 Collection 的内容,应当具备清晰领域边界、可复用接口和独立版本生命周期。这样 namespace 不只是目录前缀,而会成为组织 Roles、Modules 与 Plugins 的长期契约。