基础设施即代码 / 系统课时
锁定 Collections 与依赖版本
锁定 Collections 与依赖版本
只把 Collection 或 Role 名称写进安装命令,会让同一项目在不同时间解析到不同版本。本课把直接依赖固定到 requirements.yml,验证实际安装版本,并说明为什么可重复构建还需要同时固定 ansible-core 与传递依赖。
学习目标
- 用一个
requirements.yml同时声明并锁定 Roles 与 Collections 的直接版本。 - 使用
ansible-galaxy安装和核对依赖,及时发现环境漂移。 - 区分“固定直接依赖”和“完整锁定执行环境”,选择更可靠的交付边界。
固定直接依赖
可重复构建的第一条规则是不要使用浮动范围作为生产基线。Collection 支持版本范围,但 >= 之类约束会随仓库新增版本而解析出不同结果;Galaxy Role 则不支持版本范围。工程项目应选择已经验证过的精确版本,并通过评审主动升级。
下面的 requirements.yml 同时声明一个 Role 和一个 Collection,版本号都固定为具体发布版本:
---
roles:
- name: geerlingguy.java
version: "1.9.6"
collections:
- name: community.general
version: "7.0.0"这是完整配置文件,不是片段。实际项目应把它与 Playbook 一起纳入版本控制;升级依赖时修改版本号,并让代码评审、测试和变更记录能够看到这次升级。
从干净环境安装
在新建的虚拟机、容器或 CI Job 中执行依赖安装,比在长期使用的控制节点上反复覆盖版本更可控:
ansible-galaxy install -r requirements.yml全新环境的关键输出会明确显示被安装的固定版本,安装路径会因环境而不同:
community.general:7.0.0 was installed successfully
- geerlingguy.java (1.9.6) was installed successfully如果目标版本已经存在,命令可能报告无需重复安装,因此不要把某一条进度日志当作唯一验收条件。真正的验收应读取安装后的版本。
核对解析结果
安装完成后分别查看 Collection 与 Role。这样 CI 不只检查安装命令是否退出为 0,还能确认实际环境与仓库中的声明一致。
ansible-galaxy collection list community.general
ansible-galaxy role list | grep 'geerlingguy.java'预期结果应包含以下版本;前面的安装目录属于动态值:
# <PATH>
Collection Version
----------------- -------
community.general 7.0.0
- geerlingguy.java, 1.9.6若这里出现别的版本,不要直接用 --force 把长期环境“修到能跑”。更稳妥的做法是销毁该执行环境并按声明重新构建,因为残留的旧 Collection、Role 或 Python 包都可能继续影响模块解析。
锁住完整执行环境
精确版本的 requirements.yml 能固定直接依赖,但它不是所有场景下的完整 lockfile。Collection 自己还可以声明传递依赖,而这些依赖可能使用版本范围;此外,同一份 Collection 在不同 ansible-core、Python 或系统库版本下也可能表现不同。
因此生产交付至少应同时固定三层边界:项目仓库固定直接 Role/Collection 版本;构建流程记录或制品化解析后的传递依赖;执行环境固定 ansible-core、Python 和必要系统包。使用 Ansible Execution Environment 时,还可以把构建出的镜像按不可变标签或镜像摘要交付,让 CI 与生产运行的是同一份依赖集合。
版本升级也应作为显式变更处理:先修改 requirements.yml,在干净环境重新构建,再运行 ansible-lint、语法检查和目标 Playbook 测试。这样依赖变化从“某天安装时悄悄发生”变成一次可审查、可回滚的工程变更。