- 云原生
- 后端
- 开发工具
- 微服务
【免费下载链接】operator-sdk
SDK for building Kubernetes applications. Provides high level APIs, useful abstractions, and project scaffolding.
本文基于 operator-sdk 仓库官方升级文档 v1.6.0.md，面向使用ansible/v1、helm/v1、go/v2、go/v3及manifests/v2插件布局的既有 Operator 项目，逐项讲解从 v1.5.x 升级到 v1.6.0 时需要手工完成的 12 类改动：组件化配置、领导选举、指标与健康探针、安全上下文、ServiceAccount、Prometheus 指标端点、Catalog 构建目标等。读完本文，你将获得一份可直接照做的迁移清单，并能结合仓库内的 helm 样例工程 与 helm-operator 运行时代码验证每一项改动的真实落地形态。
迁移前须知：适用范围与升级背景
v1.6.0 的升级改动主要针对非 Go 插件（ansible/v1、helm/v1）以及go/v2、go/v3、manifests/v2的通用配置。这些改动的共同动因是：
- 与 kubebuilder/controller-runtime 生态对齐，把一批已弃用的命令行参数（如
--enable-leader-election、--metrics-addr）替换为官方推荐写法（--leader-elect、--metrics-bind-address）； - 提升 Operator 在共享命名空间下部署的安全性（独立 ServiceAccount、
securityContext加固）； - 为 Operator 开发者补齐"自建 Catalog 镜像"的 Makefile 工具链（
opm、catalog-build、catalog-push）。
在仓库当前的 helm 样例工程 中可以看到这些改动的最终形态，可作为升级后的对照基准。
一、可选：为 ansible-operator / helm-operator 配置组件配置（Component Config）
从 v1.6.0 起，ansible/v1与helm/v1项目支持通过 Kubernetes Component Config 机制为 operator 提供配置。仓库内部实现（internal/helm/flags/flag.go）中的注释明确指出：controller-runtime 已弃用 ComponentConfig 包，该能力仅用于兼容既有项目，未来版本会随 controller-runtime 升级而移除。
如需启用，需要改动 4 个文件：
① 新建config/default/manager_config_patch.yaml，内容参考 helm 样例工程的度量补丁写法（见 config/default），在 manager 容器上挂载配置：
spec: template: spec: containers: - name: manager args: - "--config=controller_manager_config.yaml" volumeMounts: - name: manager-config mountPath: /controller_manager_config.yaml subPath: controller_manager_config.yaml volumes: - name: manager-config configMap: name: manager-config② 新建config/manager/controller_manager_config.yaml，写入组件配置内容（如health.healthProbeBindAddress、leaderElection、metrics.bindAddress等 controller-runtime 支持的字段）。
③ 更新config/default/kustomization.yaml的resources列表，追加补丁文件：
resources: ... - manager_config_patch.yaml④ 更新config/manager/kustomization.yaml，加入configMapGenerator，由 kustomize 从配置文件生成名为manager-config的 ConfigMap：
generatorOptions: disableNameSuffixHash: true configMapGenerator: - files: - controller_manager_config.yaml name: manager-config apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization images: - name: controller newName: quay.io/example/memcached-operator newTag: v0.0.1注意：
disableNameSuffixHash: true是关键——它保证生成的 ConfigMap 名称不含哈希后缀，与 manager Deployment 中引用的manager-config名称精确匹配。
二、为领导选举补充 RBAC 规则（ansible/v1、helm/v1）
controller-runtime 在 v1.6.0 对应的版本中，领导选举资源已从 ConfigMap 演进为Lease（coordination.k8s.io/v1）。因此需要在config/rbac/leader_election_role.yaml中为coordination.k8s.io组和leases资源补充权限：
rules: - apiGroups: - "" - coordination.k8s.io resources: - configmaps - leases升级后的完整样例可直接参考 helm 样例的 leader_election_role.yaml：它同时包含""组的configmaps、events与coordination.k8s.io组的leases，并对configmaps/leases授予get/list/watch/create/update/patch/delete全套 verbs。
三、更新 Ansible Collections 版本（ansible/v1）
若你的项目使用 Ansible 插件布局，需要更新requirements.yml中的两个集合版本：
| 集合 | 升级目标版本 |
|---|---|
community.kubernetes | 1.2.1 |
operator_sdk.util | 0.2.0 |
collections: - name: community.kubernetes version: 1.2.1 - name: operator_sdk.util version: 0.2.0四、替换弃用的领导选举与指标地址参数（helm/v1）
v1.6.0 将 helm-operator 运行时的两个命令行参数更名：
| 弃用参数 | 推荐参数 |
|---|---|
--enable-leader-election | --leader-elect |
--metrics-addr | --metrics-bind-address |
仓库中 helm-operator 的运行时代码（internal/cmd/helm-operator/run/cmd.go）为迁移提供了明确的兼容与校验逻辑：
- 同时传入新旧两个参数（
--leader-elect与--enable-leader-election）会直接报错并退出，提示"only one of ... may be set"； - 同时传入
--metrics-addr与--metrics-bind-address同样会被拒绝。
也就是说，升级时必须只保留新参数，不能新旧并存。这些新参数对应的代码位置在 config/manager/manager.yaml：
args: - --leader-elect - --leader-election-id=memcached-operator - --health-probe-bind-address=:8081五、显式设置健康探针绑定地址（helm/v1 与 ansible/v1）
v1.6.0 之前，manager 的--health-probe-bind-address可能未显式声明，健康检查端口随 controller-runtime 默认值漂移，容易与 metrics 端口冲突。升级要求：
- helm/v1：在
config/default/manager_auth_proxy_patch.yaml的 manager 容器 args 中加入--health-probe-bind-address=:8081：
spec: template: spec: containers: - name: manager args: - "--health-probe-bind-address=:8081" ...- ansible/v1：同样加入该参数，但端口为
:6789：
spec: template: spec: containers: - name: manager args: - "--health-probe-bind-address=:6789" ...设置后，livenessProbe/readinessProbe的探针端口必须与之一致。参考 helm 样例 manager.yaml：探针分别访问/healthz与/readyz，端口均为8081。
六、为 manager Deployment 增加 securityContext（ansible/v1、helm/v1）
为满足 Kubernetes 安全加固要求，在config/manager/manager.yaml中为 Pod 与 manager 容器分别设置安全上下文：
spec: ... template: ... spec: securityContext: runAsNonRoot: true containers: - name: manager securityContext: allowPrivilegeEscalation: false当前 helm 样例的 manager.yaml 已在此基础上进一步加固：Pod 级设置了runAsNonRoot: true与seccompProfile: RuntimeDefault，容器级设置了allowPrivilegeEscalation: false并 drop 全部 capabilities（capabilities.drop: ["ALL"]），完全符合 Kubernetes "restricted" Pod Security Standard。
七、从 CSV 中移除 cert-manager 卷（manifests/v2）
OLM 尚不支持 cert-manager 自动签发证书，因此manifests/v2项目需要在config/manifests/kustomization.yaml中通过 JSON Patch 移除 manager Deployment 里的证书 volume 与 volumeMount，把证书管理交给 OLM：
#patchesJson6902: #- target: # group: apps # version: v1 # kind: Deployment # name: controller-manager # namespace: system # patch: |- # # Remove the manager container's "cert" volumeMount, since OLM will create and mount a set of certs. # # Update the indices in this path if adding or removing containers/volumeMounts in the manager's Deployment. # - op: remove # path: /spec/template/spec/containers/1/volumeMounts/0 # # Remove the "cert" volume, since OLM will create and mount a set of certs. # # Update the indices in this path if adding or removing volumes in the manager's Deployment. # - op: remove # path: /spec/template/spec/volumes/0- 若项目未使用 webhook：保持上述块整体注释即可；
- 若项目使用了 webhook：取消注释并应用该 patch。
注意 patch 中的下标（containers/1、volumes/0）与 manager Deployment 的容器/卷顺序强相关，增删容器或卷时必须同步调整索引。
八、为 Prometheus ServiceMonitor 指标端点配置 scheme 与 TLS（go/v2、go/v3、ansible/v1、helm/v1）
v1.6.0 修复了一个隐蔽问题：/metrics端点虽然声明了https端口，但因未配置tlsConfig，实际并未以 HTTPS 提供服务。由于 kube-rbac-proxy 以 sidecar 形式保护该端点，使用 Pod 内默认挂载的 ServiceAccount Token 即可正确完成认证。修改config/prometheus/monitor.yaml：
# config/prometheus/monitor.yaml spec: endpoints: - path: /metrics port: https + scheme: https + bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + tlsConfig: + insecureSkipVerify: true selector: matchLabels: control-plane: controller-manager升级后的完整形态见 helm 样例的 monitor.yaml。该样例还附带一条重要生产提示：insecureSkipVerify: true会关闭证书校验，存在中间人攻击风险，生产环境应改用 cert-manager 管理证书，通过tlsConfig.caFile等方式引用受信 CA，而不是直接跳过校验。
若你的项目已移除 kube-rbac-proxy，则必须自行通过正规 TLS 配置保护
/metrics端点，不能依赖上述 token 方案。
九、新增opm与catalog-buildMakefile 目标（go/v2、go/v3、ansible/v1、helm/v1）
v1.6.0 为需要自建 Catalog 或向既有 Catalog 追加 bundle 的开发者引入了opm、catalog-build、catalog-push三个 Makefile 目标。在 Makefile 末尾追加：
.PHONY: opm OPM = ./bin/opm opm: ifeq (,$(wildcard $(OPM))) ifeq (,$(shell which opm 2>/dev/null)) @{ \ set -e ;\ mkdir -p $(dir $(OPM)) ;\ curl -sSLo $(OPM) https://github.com/operator-framework/operator-registry/releases/download/v1.19.1/$(OS)-$(ARCH)-opm ;\ chmod +x $(OPM) ;\ } else OPM = $(shell which opm) endif endif BUNDLE_IMGS ?= $(BUNDLE_IMG) CATALOG_IMG ?= $(IMAGE_TAG_BASE)-catalog:v$(VERSION) ifneq ($(origin CATALOG_BASE_IMG), undefined) FROM_INDEX_OPT := --from-index $(CATALOG_BASE_IMG) endif .PHONY: catalog-build catalog-build: opm $(OPM) index add --container-tool docker --mode semver --tag $(CATALOG_IMG) --bundles $(BUNDLE_IMGS) $(FROM_INDEX_OPT) .PHONY: catalog-push catalog-push: ## Push the catalog image. $(MAKE) docker-push IMG=$(CATALOG_IMG)Go 项目还需额外追加 OS/ARCH 变量（供opm下载脚本使用）：
OS = $(shell go env GOOS) ARCH = $(shell go env GOARCH)当前仓库的 helm 样例 Makefile 已给出这套目标的演进版本，关键差异与用法说明：
catalog-build使用opm index add --mode semver，即按语义化版本排序将 bundle 追加进 Catalog 索引；BUNDLE_IMGS支持逗号分隔多个 bundle 镜像（如make catalog-build BUNDLE_IMGS=example.com/operator-bundle:v0.1.0,example.com/operator-bundle:v0.2.0），这些镜像必须已推送且可被拉取；- 若设置
CATALOG_BASE_IMG指向既有 Catalog 镜像，会追加--from-index $(CATALOG_BASE_IMG)参数，实现"在既有 Catalog 上增量添加 bundle"。
十、变更BUNDLE_IMG并新增IMAGE_TAG_BASE变量（go/v2、go/v3、ansible/v1、helm/v1）
为了支持make bundle-build bundle-push catalog-build catalog-push一键链路，并把镜像仓库信息固化进 Makefile，v1.6.0 做了如下变量调整：
+IMAGE_TAG_BASE ?= <registry>/<operator name> + -BUNDLE_IMG ?= controller-bundle:$(VERSION) +BUNDLE_IMG ?= $(IMAGE_TAG_BASE)-bundle:v$(VERSION)命名规则：IMAGE_TAG_BASE作为仓库与镜像名前缀，-bundle:v$(VERSION)与-catalog:v$(VERSION)分别构成 bundle 与 catalog 镜像标签。例如设置IMAGE_TAG_BASE ?= foo/bar-operator后：
make bundle-build bundle-push构建并推送foo/bar-operator-bundle:v0.0.1；make catalog-build catalog-push构建并推送foo/bar-operator-catalog:v0.0.1；- 两者最终都被推送到
docker.io/foo命名空间。
现代样例如 helm 样例 Makefile 所示，同时声明了IMAGE_TAG_BASE、BUNDLE_IMG、CATALOG_IMG三者，并支持通过make bundle-build BUNDLE_IMG=<some-registry>/<project-name-bundle>:<tag>覆盖默认值。
十一、为项目引入controller-managerServiceAccount（ansible/v1、helm/v1）
v1.6.0 起，operator-sdk init会默认脚手架一个非默认 ServiceAccountcontroller-manager，以提升 Operator 部署在共享命名空间时的安全性（避免直接使用defaultServiceAccount）。迁移既有项目需要：
# Create the ServiceAccount. cat <<EOF > config/rbac/service_account.yaml apiVersion: v1 kind: ServiceAccount metadata: name: controller-manager namespace: system EOF # Add it to the list of RBAC resources. echo "- service_account.yaml" >> config/rbac/kustomization.yaml # Update all RoleBinding and ClusterRoleBinding subjects that reference the operator's ServiceAccount. find config/rbac -name "*_binding.yaml" -exec sed -i -E 's/ name: default/ name: controller-manager/g' {} \; # Add the ServiceAccount name to the manager Deployment's spec.template.spec.serviceAccountName. sed -i -E 's/([ ]+)(terminationGracePeriodSeconds:)/\1serviceAccountName: controller-manager\n\1\2/g' config/manager/manager.yaml上述命令产生的完整 diff 如下：
# config/manager/manager.yaml requests: cpu: 100m memory: 20Mi + serviceAccountName: controller-manager terminationGracePeriodSeconds: 10 # config/rbac/auth_proxy_role_binding.yaml name: proxy-role subjects: - kind: ServiceAccount - name: default + name: controller-manager namespace: system # config/rbac/kustomization.yaml resources: +- service_account.yaml - role.yaml - role_binding.yaml - leader_election_role.yaml # config/rbac/leader_election_role_binding.yaml name: leader-election-role subjects: - kind: ServiceAccount - name: default + name: controller-manager namespace: system # config/rbac/role_binding.yaml name: manager-role subjects: - kind: ServiceAccount - name: default + name: controller-manager namespace: system # config/rbac/service_account.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: controller-manager + namespace: system仓库 helm 样例的 manager.yaml 中serviceAccountName: controller-manager已到位，service_account.yaml 也作为独立 RBAC 资源存在——这是升级后最直接的对照物。注意sed的-i -E用法在 GNU sed 与 BSD sed（macOS）下略有差异，macOS 上可先备份再原地替换。
十二、为 Makefile 增加help目标（helm/v1、ansible/v1）
Ansible/Helm 项目的 Makefile 从 v1.6.0 起提供help目标（类似--help输出），可从对应样例工程的 Makefile 中直接复制。仓库 helm 样例 Makefile 中的实现如下：
.PHONY: help help: ## Display this help. @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)它的工作原理是：扫描 Makefile 中所有目标: ## 描述形式的行并按##@ 分类分组输出。要让新增目标自动出现在make help中，只需在目标定义后追加##注释即可，例如catalog-push: ## Push the catalog image.。
升级核对清单
按顺序完成以下检查，即可认为项目已对齐 v1.6.0：
- ✅ 组件配置：4 个文件的创建/修改（若需启用）；
- ✅
leader_election_role.yaml含coordination.k8s.io/leases规则； - ✅
requirements.yml集合版本为community.kubernetes 1.2.1/operator_sdk.util 0.2.0； - ✅ 运行参数仅保留
--leader-elect、--metrics-bind-address（新旧参数不可共存，见 run/cmd.go 的校验逻辑）； - ✅ 健康探针地址显式声明（helm
:8081/ ansible:6789）； - ✅ manager Deployment 具备 Pod 级与容器级
securityContext； - ✅ webhook 项目已取消注释 cert-manager 移除 patch；
- ✅
monitor.yaml含scheme: https+bearerTokenFile+tlsConfig； - ✅ Makefile 含
opm/catalog-build/catalog-push与IMAGE_TAG_BASE； - ✅ RBAC 与 Deployment 全部切换到
controller-managerServiceAccount。
其中 4、6、8、9、10 五项可直接以 helm 样例工程 作为"升级完成态"逐文件比对，确保迁移结果与官方脚手架完全一致。
- 云原生
- 后端
- 开发工具
- 微服务
【免费下载链接】operator-sdk
SDK for building Kubernetes applications. Provides high level APIs, useful abstractions, and project scaffolding.
相关推荐
Operator SDK v1.38.0 升级指南：迁移 Kubernetes 1.30 与 Kubebuilder v4，重构 Metrics 端点安全
Operator SDK v1.38.0 升级指南：迁移 Kubernetes 1.30 与 Kubebuilder v4，重构 Metrics 端点安全 Op
云原生后端开发工具微服务Synapse安全加固完全清单：部署、配置与升级风险一次性搞清
Synapse安全加固完全清单：部署、配置与升级风险一次性搞清 Synapse 安全加固是自建 Matrix 服务器的必修课。Synapse 是用 Python
后端即时通讯从配置崩溃到无缝升级：2025 Marlin固件版本迁移全攻略
从配置崩溃到无缝升级：2025 Marlin固件版本迁移全攻略 Marlin固件作为RepRap 3D打印机的优化固件，基于Arduino平台，是全球3D打印爱
智能硬件嵌入式固件物联网
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
