企业官网建设流程全解析

• 云原生
• 后端
• 开发工具
• 微服务

本文面向使用 Operator SDK 构建 Ansible Operator 的开发者，完整讲解 v1.15.0 版本引入的 Ansible Collection 迁移：将项目依赖的community.kubernetes集合替换为官方继任者kubernetes.core（要求 >= 2.2.0），并覆盖requirements.yml配置、模块全限定名替换、安装验证以及后续相关版本的演进脉络。读完本文，你可以独立完成存量 Ansible Operator 项目的 Collection 升级，并理解该变更在 Operator SDK 文档体系与脚手架中的实际落点。

一、为什么需要这次迁移

community.kubernetes是 Ansible 社区维护的 Kubernetes 模块集合，长期作为 Ansible 与 Kubernetes 集群交互的核心依赖（提供k8s、k8s_info、k8s_scale等模块）。随着该集合进入维护尾声，社区将其功能整体迁移到由 Red Hat 官方接管的kubernetes.core集合，后续的功能修复、Kubernetes API 版本适配与新模块能力都只在kubernetes.core中演进。

Operator SDK 自 v1.15.0 起，在官方升级指南中明确要求 Ansible Operator 项目完成这一迁移。仓库中 v1.15.0 升级说明 的第一条就是该变更；实际上这一迁移动作在上一版本 v1.14.0 升级说明 中已经以完全相同的形式出现过，说明该变更在 v1.14 / v1.15 两个版本间是连续的官方要求，而不是可选建议。

从仓库文档体系也可以印证迁移的最终形态：当前 Ansible 开发技巧文档 中，Ansible Operator 项目默认依赖的已是kubernetes.core与operator_sdk.util两个集合，任务示例也统一使用kubernetes.core.k8s全限定模块名。这意味着新脚手架项目已完全切换到kubernetes.core，存量项目需要通过本文步骤完成对齐。

二、核心操作：更新 requirements.yml

requirements.yml是 Ansible Operator 项目根目录下的依赖声明文件，Ansible 依赖（Collections）都通过它安装。Operator SDK 官方脚手架默认生成该文件，具体位置与作用可参考 Ansible 测试指南 中的项目结构示例：

. ├── config ├── Dockerfile ├── Makefile ├── molecule ├── playbooks ├── PROJECT ├── requirements.yml # Ansible 依赖声明 ├── roles └── watches.yaml

2.1 修改依赖声明

在项目根目录的requirements.yml中，将（或确认）kubernetes.core集合声明为项目依赖，版本下限为2.2.0：

- name: kubernetes.core version: "2.2.0"

这是 v1.15.0 升级说明给出的标准写法。要点说明：

• name必须是kubernetes.core：如果文件中原先声明的是community.kubernetes，务必替换为kubernetes.core，两者不能混用，同一功能的模块不应同时从两个集合引入；
• version使用字符串形式"2.2.0"：这是 Ansible Galaxy Collection 依赖声明的标准格式，表示"安装 >= 2.2.0 的版本"。之所以要求 2.2.0 作为下限，是因为该版本起kubernetes.core已具备与旧community.kubernetes等价且完整的功能面；
• 如果requirements.yml中还有operator_sdk.util等其他依赖，保持不变即可。顺带说明，v1.16.0 升级说明 要求将operator_sdk.util从0.2.0升级到0.3.1，这是迁移kubernetes.core之后紧接着的配套升级，建议一并执行。

2.2 安装依赖

修改完成后，在项目根目录执行安装命令：

ansible-galaxy collection install -r requirements.yml

ansible-galaxy会按照requirements.yml中的声明从 Ansible Galaxy 拉取并安装集合。该命令与 Operator SDK 文档体系中 Ansible Operator 的标准操作一致——Ansible 开发技巧文档 中初始化新项目后同样使用该命令安装依赖，Ansible 测试指南 也要求先执行它再运行 molecule 测试场景。

安装后可以验证集合是否就位：

ansible-galaxy collection list

确认输出中存在kubernetes.core且版本不低于 2.2.0 即可。

三、模块全限定名（FQCN）替换

仅更新requirements.yml还不够。若项目中的 Playbook、Role 或任务文件里直接使用了community.kubernetes集合的模块全限定名（FQCN），需要一并替换为kubernetes.core对应的模块。

两个集合的模块一一对应，最常用的替换关系如下：

以最常见的资源管理任务为例，替换前：

- name: create a ConfigMap community.kubernetes.k8s: api_version: v1 kind: ConfigMap name: example-config namespace: default

替换后：

- name: create a ConfigMap kubernetes.core.k8s: api_version: v1 kind: ConfigMap name: example-config namespace: default

模块的api_version、kind、name、namespace、state等参数语义在两个集合中完全一致，替换 FQCN 即可，无需改动任务参数。仓库 Ansible 开发技巧文档 中的示例任务使用的正是kubernetes.core.k8s写法，可作为迁移后的正确范式对照。

四、迁移后的验证流程

完成requirements.yml修改、FQCN 替换并安装依赖后，建议按以下顺序验证：

1. 语法检查：对修改过的 Playbook/Role 执行ansible-playbook --syntax-check或ansible-lint，确认模块名解析无错误；
2. 本地试跑：按 Ansible 开发技巧文档 的方式，初始化临时项目并执行ansible-galaxy collection install -r requirements.yml后，在本地对测试集群运行任务，验证kubernetes.core.k8s模块实际可用；
3. 重建镜像：Ansible Operator 运行时依赖镜像内的集合。更新requirements.yml后需重新构建 Operator 镜像（make docker-build或operator-sdk build流程），确保运行环境中的集合与项目声明一致；
4. 端到端回归：执行 Ansible 测试指南 中描述的 molecule 场景（molecule test），覆盖资源创建、更新、删除等核心路径，确认 Operator 行为无回归。

五、该变更在版本演进中的位置

kubernetes.core迁移并非孤立的单点变更，它是一条持续演进的依赖主线，在 Operator SDK 升级指南中有清晰脉络：

• v1.14.0 / v1.15.0：正式引入kubernetes.core（>= 2.2.0）替代community.kubernetes，对应上游 PR #5249；
• v1.16.0：配套要求将operator_sdk.util集合升级到0.3.1，并新增了资源限额、kubectl.kubernetes.io/default-container注解等脚手架默认项（见 v1.16.0 升级说明）；
• v1.28.0：将kubernetes.core从2.3.1升级到2.4.0，升级说明 给出了精确的requirements.ymldiff 示例，说明后续版本采用"直接修改 requirements.yml 中版本号"的升级模式。

因此，迁移到kubernetes.core后，后续升级只需要持续关注该集合的版本演进即可，无需再处理集合更名类的大动作。

六、升级注意事项

• 版本下限不可低于 2.2.0：kubernetes.core的早期版本功能尚不完整，官方要求以 2.2.0 为起点，不建议为了兼容旧环境而降级；
• 新旧集合不要混用：同一项目中同时出现community.kubernetes.*与kubernetes.core.*会引入重复模块定义与行为歧义，迁移应一次完成；
• 镜像构建环境同步：CI/CD 中安装集合与构建 Operator 镜像的步骤都要基于更新后的requirements.yml，避免"本地可用、镜像内缺失"的部署事故；
• 存量 CR 不受影响：本次变更仅涉及 Ansible 任务执行层面的模块集合切换，不影响已部署的自定义资源（CR）与 Operator 的watches.yaml配置。

完成上述步骤后，你的 Ansible Operator 项目即与 Operator SDK v1.15.0 的官方要求对齐，并可顺畅衔接后续版本的kubernetes.core升级路径。

• 云原生
• 后端
• 开发工具
• 微服务