如何配置Golang Kubernetes Operator-Golang-PHP中文网

CRD定义必须写在Go类型中而非YAML文件里，因其由controller-gen从+kubebuilder:validation等注释及JSON标签自动生成；手动修改config/crd/bases/下的YAML会被覆盖，且缺失tag或注释将导致CRD注册失败、控制器无法响应事件。

如何配置golang kubernetes operator

CRD 定义必须写在 Go 类型里，不是 YAML 文件中

很多人第一次跑 kubebuilder create api 后，直接去改 config/crd/bases/ 下的 YAML，结果 make manifests 一执行就覆盖掉——因为 CRD YAML 是从 Go 结构体里的注释（如 //+kubebuilder:validation:Minimum=1）和字段 tag 自动生成的。

常见错误现象：kubectl apply -f 成功但控制器收不到事件，或 client.Get 返回 NotFound；根本原因是 CRD 没正确注册，而根源常是 Go 类型里缺 json: tag 或漏了 +kubebuilder 注释。

Spec 和 Status 字段必须显式声明，且带 json:"spec" / json:"status" tag，否则 controller-runtime 无法序列化
所有可配置字段建议加 // +kubebuilder:default:=... 和 // +kubebuilder:validation:...，否则 API Server 不校验输入，容易引发运行时 panic
不要手动编辑 config/crd/bases/ 下的文件——它只是生成物，修改后会被覆盖

Reconcile 函数必须处理 resourceVersion 冲突

并发 reconcile 或快速更新 CR 时，client.Update() 极易触发 409 Conflict 错误，报错信息类似 the object has been modified; please apply your changes to the latest version and try again。这不是 bug，是 Kubernetes 的乐观锁机制在起作用。

典型错误做法：拿到 CR 实例 → 改 Status 字段 → 直接 r.Update(ctx, &cr) → 忽略错误或简单重试一次就放弃。

更新 Status 必须用 r.Status().Update(ctx, &cr)，不能走普通 Update
更新 Spec 或其他字段优先用 client.Patch(ctx, &obj, client.MergeFrom(&oldObj))，只提交变更部分，天然避开 conflict
如果必须全量 Update（比如重建整个对象），务必包一层 retry.RetryOnConflict，否则第一次失败就退出，状态卡死
永远检查 err != nil 后立刻 return ctrl.Result{}, err，别吞掉 IsNotFound 或 IsForbidden 这类关键错误

RBAC 权限不全会导致 Reconcile 根本不触发

控制器启动成功、日志里没报错，但你改了 CR，Reconcile 就是不执行——大概率是 RBAC 缺权限。Kubernetes 不会主动告诉你“watch 被拒绝”，而是静默跳过事件监听。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

常见错误现象：make deploy 后控制器 Pod Running，但 kubectl get events -n my-operator-system 看不到任何关于你的 CR 的事件；kubectl auth can-i list mydatabases.database.example.com 返回 no。

config/rbac/role.yaml 必须包含对目标 CR 的 get、list、watch 权限，缺 watch 就不会触发 reconcile
如果控制器要操作 Deployment/Service 等内置资源，对应 resources 和 verbs 也得列全，比如 deployments/status 是单独的子资源，漏掉就无法更新 Ready 状态
本地调试用 make run ENABLE_WEBHOOKS=false，避免证书问题干扰权限验证路径

OwnerReference 绑定错误会让子资源变成“孤儿”

Operator 创建的 Deployment、Secret 等资源，如果不打上正确的 ownerReferences，删除 CR 后这些资源不会自动清理，下次创建同名 CR 还可能因命名冲突失败。

典型错误：手动生成 Deployment 对象后直接 client.Create，没调用 ctrl.SetControllerReference(&mycr, &dep, r.Scheme)。

必须在创建子资源前调用 ctrl.SetControllerReference，传入当前 CR 实例、待创建对象、以及 reconciler 的 Scheme
确保 CR 实例已通过 r.Get 加载（含 metadata.UID），否则 SetControllerReference 会静默失败
子资源的 namespace 必须和 CR 一致（除非明确支持跨 namespace 管理），否则 OwnerReference 无效

控制器逻辑本身不难写，难的是让每一步都经得起并发、中断、权限变化和版本升级的考验。最常被忽略的点是：Status 更新走错 subresource、OwnerReference 漏设、以及把 CRD 当成静态 YAML 去维护。