基础设施即代码 / 系统课时

使用 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 命名空间、目录与 FQCN 的对应关系

创建并运行最小 Collection

下面的命令创建 acme.platform,再加入一个 banner Role 和测试 Playbook。示例使用独立实验目录,不依赖系统级 Collection 安装路径。

bash
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 版本不同会使任务计数和格式略有差异。

text
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 的长期契约。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Collections 组织内容

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通