Operator-SDK v1.42.0 实战：基于 Helm Chart 开发 K8s Operator 全流程指南

继上一篇文章介绍了如何使用 Kubebuilder 开发 Operator 后，本文将带你完成一次从零到一的实战：使用 Operator-SDK 并基于 Helm Chart 的方式，开发一个 Kubernetes Operator。

我们将采用一个开源示例项目的逻辑进行套用和讲解，目标是让你掌握这种“无需编写 Go 代码”的 Operator 实现方式。完整的示例代码可以参考 GitHub 仓库：https://github.com/baidingtech/operator-lesson-demo/blob/main/operator-sdk

实验环境说明

• Kubernetes 版本：v1.29.9
• Helm 版本：v3.9.4
• operator-sdk 版本：v1.42.0 (当前最新版)

第一步：创建 Helm Chart

首先，我们需要为示例应用创建一个 Helm Chart，这将是后续 Operator 管理的模板。

1. 创建项目目录并初始化 Chart：

   mkdir -p /opt/code/helm-operator-test
   cd /opt/code/helm-operator-test
   helm create app-chart

2. 自定义修改 app-chart 中的资源模板和配置文件。核心在于将 Helm 资源的使用方式设计成类似于 CRD 的形态，这步本质上就是在设计 CRD。

   • 修改 templates/ 下的资源文件：根据你的应用需求，调整 deployment.yaml、ingress.yaml、service.yaml 等模板。例如，ingress.yaml 模板可能如下所示，使用了变量来动态配置：
     
   • 设计 values.yaml：这个文件中的字段，将与后续我们通过 CR 实例传递的参数一一对应。你可以将其理解为 CRD 的 Schema 设计。

     # Default values for app-chart.
     # Declare variables to be passed into your templates.
     image: nginx:latest
     name: app-sample
     replicas: 3
     enable_ingress: true
     enable_service: true

     

3. 验证 Chart 渲染结果是否正确：

   helm template app-chart

第二步：安装 Operator-SDK

参考官方文档进行安装：https://sdk.operatorframework.io/docs/installation/

对于 Linux amd64 系统，可以通过以下命令获取下载链接（建议手动下载后上传至服务器，速度更快）：

export ARCH=$(case $(uname -m) in x86_64) echo -n amd64 ;; aarch64) echo -n arm64 ;; *) echo -n $(uname -m) ;; esac)
export OS=$(uname | awk '{print tolower($0)}')
export OPERATOR_SDK_DL_URL=https://github.com/operator-framework/operator-sdk/releases/download/v1.42.0
echo ${OPERATOR_SDK_DL_URL}/operator-sdk_${OS}_${ARCH}

下载完成后，将其放入系统路径并赋予执行权限：

mv operator-sdk_linux_amd64 /usr/local/bin/operator-sdk
chmod +x /usr/local/bin/operator-sdk

第三步：创建 Operator-SDK 项目

现在，使用我们准备好的 Helm Chart 来初始化一个 Operator 项目。

mkdir -p /opt/code/helm-operator-test/helm-operator-sdk
cd /opt/code/helm-operator-test/helm-operator-sdk
operator-sdk init --plugins helm --domain baiding.tech --group ingress --version v1alpha1 --kind App --helm-chart ../app-chart

命令执行后，会生成标准的项目目录结构。

其中，Dockerfile 基于一个预置的 Helm Operator 镜像，这个镜像已经包含了 Controller 的监听和协调逻辑。

工作原理简述

这种 Helm-based Operator 的工作流程非常清晰：

1. 定义 CR 实例：用户创建一个 YAML 文件（例如 ingress_v1alpha1_app.yaml），其中 spec 字段包含了应用的配置。
   
2. Operator 监听：Operator 启动后，会读取 watches.yaml 配置文件，得知需要监听特定类型（group: ingress.baiding.tech, kind: App）的资源。
   
3. 值覆盖与渲染：当监听到 CR 变化时，Operator 会将 CR 中 spec 的字段值提取出来，覆盖 Helm Chart 中 values.yaml 的默认值。
   
4. 部署资源：Helm 引擎使用合并后的值渲染 templates/ 目录下的模板，生成最终的 Kubernetes 资源（如 Deployment、Service 等），并将其部署到集群中。
   

通过这种方式，你无需编写 Go 协调逻辑，只需维护好 Helm Chart，就能实现一个功能完整的 Operator。

第四步：本地测试 Operator

在将 Operator 正式部署到集群前，我们先在本地进行测试。

1. 安装 CRD：

   make install

   执行后，检查 CRD 是否创建成功：

   kubectl get crd | grep ingress

   

2. 本地运行 Operator：

   make run

   注意：如果此命令长时间卡住，可能是它在后台下载 helm-operator 二进制文件（从 GitHub，可能较慢）。解决方法请见文末的“常见问题处理”。
   

3. 创建并测试 CR 实例：
   保持 config/samples/ingress_v1alpha1_app.yaml 文件内容默认（或按需修改），然后应用它：

   kubectl apply -f config/samples/ingress_v1alpha1_app.yaml

   
   查看 Operator 是否成功创建了对应的 Kubernetes 资源：

   kubectl get deploy,pod,svc,ingress | grep -v zcywwebapp-sample | grep app-sample

   

第五步：部署 Operator 到集群

测试通过后，我们可以将 Operator 构建成镜像并部署到 Kubernetes 集群中。

1. 清理测试环境：

   kubectl delete -f config/samples/ingress_v1alpha1_app.yaml

   然后按 Ctrl+C 停止本地运行的 make run 进程。

2. 构建并推送 Operator 镜像：
   修改命令中的镜像仓库地址为你自己的。

   make docker-build docker-push IMG=registry.cn-chengdu.aliyuncs.com/qiuyl01/zcywapp-operator-helm-demo:v1.0

   

3. 部署 Operator（CRD 和 Controller）：

   make deploy IMG=registry.cn-chengdu.aliyuncs.com/qiuyl01/zcywapp-operator-helm-demo:v1.0

   
   （如需删除，可运行 make undeploy）

4. 验证集群部署：
   再次创建 CR 实例，验证由集群中 Operator 管理的资源是否正常创建。

   kubectl apply -f config/samples/ingress_v1alpha1_app.yaml
   kubectl get deploy,pod,svc,ingress | grep -v zcywwebapp-sample | grep app-sample

   

进阶：使用 Kustomize 导出部署清单

有时，你可能需要一份统一的 YAML 文件用于离线部署或 GitOps。我们可以使用 Kustomize 来生成。

kustomize build config/default > all-in-one-deploy.yaml

然后，你可以用这一份文件部署整个 Operator：

kubectl apply -f all-in-one-deploy.yaml

之后，像之前一样应用 CR 实例即可。

常见问题处理

问题：执行 make run 后卡住，无响应。
原因：该命令在后台尝试从 GitHub 下载 helm-operator 二进制文件，网络不佳时会导致卡顿。
解决：

1. 另开一个终端，执行 ps aux | grep helm-operator，找到下载进程和下载链接。
2. 手动下载 https://github.com/operator-framework/operator-sdk/releases/download/v1.42.0/helm-operator_linux_amd64。
3. 将其替换到项目 bin/ 目录下的对应文件（可能需要先终止 make run 进程）。

   # 在项目 bin/ 目录下操作示例
   mv helm-operator_linux_amd64 helm-operator
   chmod +x helm-operator

   

4. 再次执行 make run，即可顺利启动。

总结

至此，你已经完成了使用 Operator-SDK 基于 Helm Chart 开发 Kubernetes Operator 的全流程。这种方式极大地降低了入门门槛，你不需要编写 Go 代码，只需具备 Helm 和 Kubernetes 的基础知识，通过设计好 Chart 的 values.yaml，就能快速实现一个 Operator。

当然，这种方式的灵活性不及直接用 Kubebuilder 编写协调逻辑。对于复杂的、需要精细控制资源生命周期和状态的需求，建议还是采用 Kubebuilder 方式。但对于许多简单的“部署包管理”场景，Helm-based Operator 是一个非常高效和实用的选择。

希望这篇实战指南对你的 云原生 学习和 运维 实践有所帮助。如果在实践过程中遇到其他问题，欢迎在技术社区进行交流和探讨。