Operator SDK v1.11.0 升级指南：Ansible Roles 路径、KUBEBUILDER_ASSETS 导出与清单协议字段迁移

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

本指南基于 operator-sdk 官方升级文档（website/content/en/docs/upgrading-sdk-version/v1.11.0.md）整理，面向从 v1.10.x 及更早版本升级到 v1.11.0 的 operator 开发者。你将掌握四项关键迁移动作：为本地make run注入 Ansible Roles 路径、在 go/v3 项目中正确导出KUBEBUILDER_ASSETS、为服务清单补齐containerPort的protocol字段，以及按新标准提升 controller manager 的资源限制。文中所有配置均可在仓库的生成模板与测试数据（testdata/）中找到对应实现，可直接对照落地。

升级背景与变更总览

operator-sdk v1.11.0 的完整变更记录保存在 changelog/generated/v1.11.0.md 中，主要包括三类内容：

• 新增能力：为 helm 类 operator 增加基于watches.yaml选择器的资源过滤 predicate（PR #4997）；支持以 Gotext/template展开 helm override values（PR #5105）。
• 行为变更：go/v3、ansible/v1、helm/v1 三类项目统一提高 controller manager 资源限制（PR #4863）；升级 operator-framework 依赖至 0.10.5，修复 bundle 校验中对无效 ServiceAccount 的判断（PR #5119）。
• 缺陷修复：修复 ansible operator 本地运行时 playbook 导入的 roles 找不到的问题（PR #5118）；修复无 body 请求的 metadata 归属（PR #5064）；generate bundle不再重复生成 CSV 中已有的 ServiceAccount（PR #5120）。

本文聚焦升级文档明确要求人工介入的四项手动迁移步骤，其余变更由脚手架工具自动覆盖。

一、为make run注入本地 Ansible Roles 路径（ansible 项目）

适用场景：使用 Ansible 构建的 operator，同时包含 Roles 与 Playbooks。

问题根因：在 v1.11.0 之前，当脚手架同时生成 Roles 与 Playbooks 时，playbook 导入的 roles 在本地运行时（make run）无法被 Ansible 找到。这是因为本地工作目录下的roles/并未进入 Ansible 的角色搜索路径，只有集群内运行时（镜像内将 roles 打进特定目录）才正常。

迁移操作：修改Makefile中的run目标，将本地roles目录前置追加到ANSIBLE_ROLES_PATH环境变量：

run: ## Run a controller from your host. ANSIBLE_ROLES_PATH="$(ANSIBLE_ROLES_PATH):$(shell pwd)/roles" $(ANSIBLE_OPERATOR) run

关键点解析：

• $(ANSIBLE_ROLES_PATH)保留原有路径，:$(shell pwd)/roles以冒号分隔追加当前目录下的roles/，二者顺序保证本地 roles 优先被解析；
• $(shell pwd)在 Makefile 中动态求值，无需硬编码绝对路径，任何克隆位置均可直接使用；
• 该修复对应 PR #5118，同时也在 changelog/generated/v1.11.0.md 的 Bug Fixes 一栏有明确记载。

验证方式：修改后执行make run，观察 playbook 中import_role/include_role对应任务是否正常解析，不再报 "couldn't resolve role/playbook" 类错误。

二、go/v3 项目导出KUBEBUILDER_ASSETS修复make test

适用场景：go/v3 语言类 operator 项目，使用setup-envtest下载 kubebuilder 测试资产。

问题根因：v1.11.0 修复了make test因 envtest 资产路径未正确设置而失败的 bug（PR #4863）。修复前go test ./...直接运行，无法定位到setup-envtest下载的 kube-apiserver、etcd 等二进制所在目录。

迁移操作：在Makefile中补充环境变量声明，并让测试命令显式使用 envtest 资产路径：

+# ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary. +ENVTEST_K8S_VERSION = 1.21 test: manifests generate fmt vet envtest ## Run tests. - go test ./... -coverprofile cover.out + KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" go test ./... -coverprofile cover.out

参数说明：

前提条件：envtest目标已通过setup-envtest安装（脚手架默认提供ENVTEST ?= $(LOCALBIN)/setup-envtest相关定义）。只有先执行make envtest完成二进制下载，use -p path才能返回有效目录。

三、为服务清单补齐containerPort的protocol字段

适用场景：go/v3、ansible/v1、helm/v1 三类项目。

背景：Kubernetes 服务端应用（server-side apply）要求 Service 端口的protocol字段显式存在，否则清单在 apply 时会因缺少该字段而报错或产生冲突。v1.11.0 因此在脚手架生成的清单中统一补上protocol: TCP（PR #4863）。

迁移操作：分别修改以下文件。

3.1 指标代理 Service（三类项目通用）

在config/default/manager_auth_proxy_patch.yaml与config/rbac/auth_proxy_service.yaml中为 8443 端口补上协议声明：

ports: - containerPort: 8443 + protocol: TCP name: https

说明：不同版本脚手架对这两个文件的命名略有差异，例如当前仓库的 helm 示例中对应文件为 config/default/manager_metrics_patch.yaml 与 config/default/metrics_service.yaml，迁移时以你项目config/下实际存在的文件为准。

3.2 Webhook Service（仅 go/v3 项目）

在config/webhook/service.yaml中为 443 端口补上协议声明：

ports: - port: 443 + protocol: TCP targetPort: 9443

迁移后的目标状态：当前仓库testdata中的新模板已包含上述字段，可直接对照验收。例如 helm 示例的 metrics_service.yaml 中protocol: TCP已就位（port: 8443之上），go 示例的 config/webhook/service.yaml 中 443 端口同样带有protocol: TCP。

四、提高 controller manager 资源限制

适用场景：go/v3、ansible/v1、helm/v1 三类项目。

背景：v1.11.0 将脚手架默认的 controller manager 资源限制从100m / 30Mi提升至200m / 100Mi（PR #4863）。原默认值过于保守，在指标采集、leader election、webhook 等组件同时运行时常触发 OOMKilled 或 CPU 限流。

迁移操作：修改config/manager/manager.yaml中 Deployment 的 resources 段：

resources: limits: - cpu: 100m - memory: 30Mi + cpu: 200m + memory: 100Mi

两点提醒：

1. 仅更新 limits 即可：requests不在此次变更范围内，可按实际负载另行规划；
2. 按需二次调整：200m / 100Mi是脚手架默认值，生产环境应根据 operator 实际资源画像继续上调。参考当前仓库 helm 示例的 config/manager/manager.yaml，其中已演进为limits: cpu: 500m, memory: 128Mi、requests: cpu: 10m, memory: 64Mi，说明后续版本仍在持续放宽默认值。

五、迁移后的整体验证清单

完成上述四项修改后，建议按以下顺序回归验证：

1. 单元测试：make test，确认 envtest 资产路径注入生效、测试套件正常启动 apiserver；
2. 本地运行：make run，确认 ansible roles 可解析、controller 正常启动且指标端口（8443）可访问；
3. 清单检查：kubectl apply --server-side -f config/default/或make deploy，确认无 protocol 字段缺失类报错；
4. 资源观察：部署后kubectl top pods观察 manager 容器 CPU/内存，确认200m / 100Mi上限与实际用量匹配，必要时继续调整。

若需查看其他版本的升级说明，可参考 version-upgrade-guide.md 及 upgrading-sdk-version 目录 下的各版本迁移文档；完整 v1.11.0 变更明细见 changelog/generated/v1.11.0.md。

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