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

选择 ansible-core 与 Collections

选择 ansible-core 与 Collections

现代 Ansible 项目需要把“自动化运行时”和“具体自动化内容”分开管理。ansible-core 提供执行引擎、CLI、Playbook 解析和插件框架,Collections 则承载大量模块、插件和角色。把两者分别锁定版本,可以让项目升级、依赖审计和环境复现更可控。

学习目标

  • 区分 ansible-core、社区 ansible 包与 Collections 的职责
  • 判断项目应该固定哪些运行时和内容依赖
  • 使用 ansible-galaxy 查看并安装项目所需 Collection

先分清运行时和自动化内容

ansible-core 是核心运行时,其中包含 ansible、ansible-playbook、ansible-inventory 等命令,以及 Playbook 执行引擎和一组内置插件、模块。名称以 ansible.builtin 开头的内容随 ansible-core 提供,不需要额外安装一个名为 ansible.builtin 的 Collection。

Collections 是独立发布的内容包,可以提供模块、连接插件、过滤器、角色等。例如某个云平台、网络设备或数据库的模块可能来自对应 Collection,而不是 ansible-core 本身。完全限定名称通常写成 namespace.collection.plugin,这样可以明确任务究竟依赖哪一个内容包。

PyPI 上的社区 ansible 包则提供一个更完整的发行组合,它依赖 ansible-core,同时带有一组社区维护的 Collections。用于学习和通用交互很方便,但需要严格控制生产依赖时,通常更适合显式管理 ansible-core 与项目所需 Collections。

检查当前运行时版本

先确认实际执行命令使用的是哪个 ansible-core 和 Python 环境:

bash
ansible --version

预期输出

text
ansible [core <VERSION>]
  config file = <PATH>
  configured module search path = <PATH>
  ansible python module location = <PATH>
  executable location = <PATH>
  python version = <VERSION> (<PATH>)

版本号和路径会随安装方式变化。排查“本机可以运行、CI 却失败”时,这几行尤其重要,因为同名 ansible 命令可能来自不同虚拟环境或 Python 安装位置。

用 requirements.yml 固定 Collections

不要依赖某台机器“恰好已经装过”的 Collection。项目可以使用 requirements.yml 明确声明内容依赖。下面以 community.general 为例,版本号只是项目锁定方式的示范,实际项目应选择经过验证并与当前 ansible-core 兼容的版本。

yaml
collections:
  - name: community.general
    version: "<VERSION>"

安装声明的 Collection:

bash
ansible-galaxy collection install -r requirements.yml

预期输出

text
Starting galaxy collection install process
...
community.general:<VERSION> was installed successfully

网络源、安装目录和附加日志可能不同。安装完成后,可以查看本机可发现的 Collections:

bash
ansible-galaxy collection list

预期输出

text
# <PATH>
Collection        Version
----------------- -------
community.general <VERSION>

在 Playbook 中显式使用内容来源

调用模块时优先使用完全限定集合名称,也就是 FQCN。这样代码审查时不必猜测短模块名来自哪里,也能减少不同 Collection 提供同名插件时的歧义。

yaml
- name: Verify managed hosts
  hosts: all
  gather_facts: false
  tasks:
    - name: Check Ansible module execution
      ansible.builtin.ping:

这是配置片段示例,需要已有 Inventory 和可连接的受管主机。ansible.builtin.ping 来自当前 ansible-core;若任务改用第三方 Collection 的模块,则还需要确保对应 Collection 已通过项目依赖安装。

建立可复现的版本边界

一个稳定项目至少应同时记录运行时和内容版本:Python 环境固定 ansible-core,requirements.yml 固定第三方 Collections,并在升级前检查目标 Collection 声明的 requires_ansible 等兼容性约束。不要因为 Collection 可以独立升级,就默认任意新版本都兼容当前运行时。

选择原则并不复杂:需要的是执行能力时看 ansible-core,需要的是某个平台或领域的模块、插件与角色时看 Collections;希望快速获得社区整合发行版时可以使用 ansible 包。生产项目再进一步把这些依赖显式锁定,才能让开发机、CI 和自动化执行环境使用同一套能力边界。

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

目录与阅读设置

阅读设置

17

记录一个想法

选择 ansible-core 与 Collections

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

登录哪都通