如果你已经在 Kubernetes 上部署过几次应用大概率遇到过这种情况Deployment 挂了三副本其中一副本被 node 驱逐过一会儿它自己又起来了——这是内置控制器在做心愿达成但你要是部署的是一个有状态的东西比如一套数据库集群、一套分布式缓存升级要先备份、故障要自动切换、扩容不是简单加一个 Pod——Kubernetes 就不管了。过去大家靠人肉运维靠脚本靠 cron维护成本极高而且容易漏。后来社区形成了更体系化的做法把运维逻辑写成一个常驻进程让 Kubernetes 用声明式的方式驱动它这个模式就是 kubernetes operator。而 kubebuilder 是目前最主流的 Operator 开发框架底层大量封装了 controller-runtime 的机制。这篇文章我先不展开脚手架命令先把 Operator 的工作原理讲透。因为我在实际带团队时反复发现很多人会用 kubebuilder 生成项目能跑起来但 Reconcile 为什么会被调用、为什么自己改了状态又触发一次、Informer 和 WorkQueue 到底在里面扮演什么角色这些不搞清楚写出来的东西只能是会调 API 的脚本一旦遇到复杂状态就失控。这篇内容适合已经能熟练部署 Deployment、Service、Pod正准备进入自定义控制器开发的读者原理通了后面任何框架都只是壳。1. Operator 到底在解决什么问题1.1 Kubernetes 天生就是一个声明式自动巡航系统Kubernetes 自己的架构就是大规模控制器集群。你kubectl apply一个 Deployment 文件里面写的是我要三个副本、镜像 nginx:1.24、端口 80这是你的期望状态。API Server 负责把这份声明存进 etcd然后一堆控制器就开始盯着它干活Deployment 控制器发现 ReplicaSet 数量不对就去创建ReplicaSet 控制器发现 Pod 数量不对就去创建 Pod调度器发现 Pod 还没落节点给它选一台机器kubelet 发现节点上有 Pod 没启动容器就拉镜像启动。这一整套动作没有谁在命令谁每个组件都只做一件事读当前状态对比期望状态如果有差距就执行动作让现状靠近期望。你用户侧只负责声明不负责指挥。这就是声明式 API 和控制循环的威力——系统里任何一步被干扰、被打断、被删掉控制器都会在下一轮循环里把它纠正回来。这也是理解 Operator 的第一块基石控制器不是执行一次任务而是永远在奔向期望状态的路上。你写一个控制器本质是在给 Kubernetes 增加一种新的纠偏能力。1.2 Controller 与 Operator从内置逻辑到业务逻辑Kubernetes 内置控制器很全能但只局限于它认识的内置资源Deployment、Service、ConfigMap、Ingress 这些。一旦你说我要一个生产可用的数据库集群包含 5 个节点、一主多从、自动故障切换、每天凌晨备份、升级前先冻结写入Kubernetes 就听不懂了。这时候需要两样东西配合CRDCustom Resource Definition让 Kubernetes 认识你的新资源类型。你定义一个DatabaseCluster里面有spec.replicas、spec.version、spec.backup.enabled等字段。从此kubectl get databaseclusters也能用了。Controller / Operator真正实现如何把这个 DatabaseCluster 落到现实里。它 watch 用户创建的数据库集群实例然后负责去创建 StatefulSet、Service、备份 CronJob监控故障执行切换更新状态。Operator 这个词和 Controller 基本是同一个东西只是更强调业务领域知识。举个例子Deployment 控制器像是标准家政服务只做保证有 N 份这个通用约定而 Operator 像是专属管家它懂你家每一件电器的脾气——哪个要先备份再升级哪个故障了要切换到备机哪个挂了你得先通知业务方。它把人类的运维知识变成了代码里的判断逻辑。所以我的理解是Operator CRD扩展资源模型 Controller控制循环 领域运维知识。三者缺一个都不是完整意义上的 Operator。1.3 哪些场景才值得写 Operator这部分我必须泼点冷水。不是所有东西都值得写成 Operator。我见过有人把创建一个 Deployment Service这种五分钟手工活也封装成 Operator结果维护成本比手动 apply 高了一个数量级。真正值得写 Operator 的信号我总结为这四条资源有生命周期管理需求安装、升级、备份、恢复、删除清理每一步都不是单纯 apply 能搞定的。存在可固化的故障补救规则比如主节点失联超过 30 秒把备节点提升为主节点这种明确规则值得让程序反复执行。需要和外部系统联动需要去云平台创建负载均衡、存储卷、DNS 记录然后等待外部状态就绪。需要根据业务状态自动扩缩容或配置变更单纯 HPA 不够要从业务指标决定拓扑变化。如果是部署一次静态 YAMLHelm Chart 就够用了如果是周期性清理任务CronJob 更合适。写 Operator 意味着你要长期维护一个控制器的正确性、权限、版本兼容性这是一笔不小的工程成本。先确认痛点是重复性强、规则明确、人工容易出错再动手。2. 控制循环Operator 的心脏2.1 期望状态、实际状态与调谐Reconcile控制循环这个词听起来高大上其实你可以把它想成空调的恒温器你设了 24 度这是期望状态房间里实际 28 度这是实际状态空调一直读温度计温度高了制冷、低了加热直到接近 24 度它就进入低频待机哪天窗户开了温度又升上去它继续工作。人设定完温度之后就不需要反复操作了。Kubernetes 的控制循环完全一样。用户定义的 CR 的spec就是24 度集群里真实存在的 Deployment、Pod、Service、外部云资源就是实际温度控制器里的核心函数Reconcile就是温度比较和调整逻辑。它做三件事先读期望状态从 CR 的 spec 里拿、再读实际状态从集群里查、然后执行动作让两者尽量一致。这里有个新手最容易误解的点Reconcile 不是事件回调不是用户创建了 CR 我执行一次就完事。它是被反复触发的创建触发、更新触发、子资源变化触发、甚至什么都不发生控制器还会周期性回来检查一遍。这在机制上叫 resync。为什么要这样因为集群状态随时可能被别的东西改变只有周期性地重新对比才能保证声明最终被实现。理解这一点之后你就不会写只在创建时做初始化这种控制器了。2.2 从 Watch 到 Diff 到 Act 到 Update 的标准四步控制循环的每次执行拆开看都是固定四步Watch监听控制器先要订阅感兴趣的资源。至少包含它自己管理的 CRD 类型通常还会监听它创建出来的子资源比如 Deployment、Pod。任何相关的增删改都会变成一次入队信号。Diff对比拿到资源后读取 spec 里的期望值再去查实际状态。实际的 Deployment 存在吗副本数对吗镜像版本对吗状态里有没有异常Act执行根据差异决定动作。没创建就创建规格不一致就更新资源要删除就清理。如果涉及外部系统这一步通常还包含调用云 API、等待结果。Update更新状态把这次循环的结果写到 CR 的status字段里。这一步很关键因为用户和上层系统是通过 status 来判断当前进展的。而且 status 一更新又会触发 Watch开启下一轮 Reconcile。我给你画一个简化但不失真的节奏假设控制器管理一个MyApp资源它期望创建 2 个副本。第一次 Reconcile 发现 Deployment 不存在于是创建第二次 Reconcile 发现 Deployment 存在但可用副本还是 0于是什么都不改把 status.availableReplicas 更新为 0第三次 Reconcile 发现 Deployment 可用副本为 1继续更新状态直到可用副本变成 2status 写入 2此时期望和实际一致Reconcile 进入观察模式。每次循环本身都很廉价关键是循环逻辑必须可以反复执行而且每次执行结果一致。2.3 Informer 机制为什么不能直接打 API那你可能会想循环里直接调 Kubernetes API 把资源全部 List 一遍不就行了小规模没问题规模一大就完蛋。比如集群里有 500 个MyApp每个MyApp又管理 3 个子资源如果每 10 秒全量 List 一次API Server 会被打爆。所以 controller-runtime 用了 Informer 机制。它做的事情可以理解成订阅制而不是轮询制首次启动时做一次 List拿到全量对象建立本地缓存之后通过 Watch 监听增量事件不停更新缓存所有读操作优先走本地缓存只有写操作才直接请求 API Server如果 Watch 连接断了Informer 会重新 List 兜底保证缓存不出错。另外Watch 到的原始事件不会直接调你的 Reconcile而是先丢进一个 WorkQueue。WorkQueue 会对相同资源的多个事件做去重合并——短时间内同一个资源变化了十次队列里可能只留一个请求处理失败还会指数退避重试。这就是为什么 Reconcile 收到的请求里只有一个namespace/name而不是完整的事件数据。有个隐含设计很多人没意识到正因为 Reconcile 只拿到一个对象名字它必须重新去读 API所以就算事件丢了、队列出错了下一轮循环也能从当前状态重新收敛。这是整个控制器模型健壮性的根源——它不依赖事件传输不丢而依赖每次重算都基于当前事实。2.4 事件、队列与幂等设计的必然性理解了队列的合并与退避你就会明白一个结论你永远不知道这一次 Reconcile 究竟是因为什么被触发的。可能是创建可能是状态更新可能是子资源变化也可能是周期性 resync。控制器代码里如果写了if 事件创建这种思路一开始就错了。正确姿势是不管因为什么被触发每次都完整执行读 spec、读现状、做 diff、执行动作。具体到一个细节你创建完 Deployment 后要不要立刻在同一个 Reconcile 里等它就绪不要。因为 Deployment 的可用状态变化会再次触发你的 Reconcile你只需要在下一次循环里检查它就行。这种各管一段、循环推进的设计让整个系统几乎不需要锁也不需要复杂的编排状态。我早期写控制器踩过一个典型的坑为了优化性能把创建 Deployment 之后的等待逻辑放在同一个 Reconcile 里死循环探测结果一方面阻塞了 worker 线程另一方面一旦中途失败WorkQueue 重试时又会重复创建。后来我终于明白控制循环的正确姿势是一步到位然后回来看结果而不是一次调完所有步骤。你每一步都应该是幂等的创建前先查存在不存在更新前先比字段一不一样外部 API 调用要做去重和重试准备。3. Kubebuilder把控制器原理工程化3.1 脚手架帮我们建了什么原理归原理从零写一个控制器要处理大量重复工程Informer 初始化、WorkQueue 创建、Leader 选举、指标暴露、Webhook 服务、RBAC 清单……Kubebuilder 的价值就是把这些全部固化成语料和代码骨架让开发者只专注于 CRD 类型和 Reconcile 逻辑。我用kubebuilder init和kubebuilder create api生成一个项目后核心目录大概长这样路径作用你需要关心的程度api/v1/CRD 的 Go 类型定义、DeepCopy 方法高你的资源字段在这里定义controllers/控制器实现Reconcile 逻辑的所在地很高核心业务代码config/crd/从 Go 类型生成的 CRD YAML 清单中主要靠 make manifests 生成config/rbac/控制器操作各类资源所需权限高写错了直接 403main.go组装 Manager、注册 Controller、启动 Webhook低默认代码基本够用Makefile封装 generate/manifests/install/run 等命令高开发循环都靠它其中main.go里的 Manager 是进程骨架它把所有组件缝合在一起缓存、客户端、控制器、Webhook、健康检查、指标端口。你写的每个控制器都要注册到这个 Manager 上Manager 启动后才会拉起对应 worker 循环。3.2 编写 CRD定义属于你的资源在 Kubebuilder 里资源类型是用 Go struct 定义的。一般分为 Spec 和 Status 两部分。我习惯给团队解释成Spec 是用户填的订单Status 是控制器写的发货状态。用户只写订单控制器不断更新发货状态两边互不干扰。下面是一个最小示例假设我们要定义一个叫MyApp的资源type MyAppSpec struct { Replicas int32 json:replicas Image string json:image } type MyAppStatus struct { AvailableReplicas int32 json:availableReplicas Phase string json:phase,omitempty } type MyApp struct { metav1.TypeMeta json:,inline metav1.ObjectMeta json:metadata,omitempty Spec MyAppSpec json:spec,omitempty Status MyAppStatus json:status,omitempty }定义好类型之后make generate会生成 DeepCopy 方法make manifests会从 Go 类型生成 CRD 的 YAML。生成的 YAML 里会体现字段的校验规则比如apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: myapps.sample.example.io spec: group: sample.example.io versions: - name: v1 schema: openAPIV3Schema: properties: spec: properties: replicas: format: int32 type: integer image: type: string type: object status: properties: availableReplicas: format: int32 type: integer type: object scope: Namespaced想做必填校验、枚举值、正则也是通过 Go 类型上的kubebuilder:validation注释来实现。这里提醒新手一件事版本字段和 API group 一旦发布改起来代价很高。不要一上来就搞 v2 多版本支持先老老实实 v1 单版本等用户真多了再考虑版本转换。3.3 编写 ControllerReconcile 函数就是全部真相Kubebuilder 生成的 controller 骨架里你真正要写的东西其实就一个函数外加一个SetupWithManager方法。SetupWithManager做的事情就是向 Manager 声明我关注MyApp主资源同时关注我做出来的Deployment子资源。func (r *MyAppReconciler) SetupWithManager(mgr ctrl.Manager) error { return ctrl.NewControllerManagedBy(mgr). For(samplev1.MyApp{}). Owns(appsv1.Deployment{}). Complete(r) }这段代码揭示的原理是For声明主资源Owns声明子资源。一旦MyApp变化或者它拥有的Deployment变化事件都会进入同一个 WorkQueue最终都会调到Reconcile。而Reconcile函数长这样func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { var app samplev1.MyApp if err : r.Get(ctx, req.NamespacedName, app); err ! nil { return ctrl.Result{}, client.IgnoreNotFound(err) } dep : appsv1.Deployment{} err : r.Get(ctx, types.NamespacedName{Namespace: app.Namespace, Name: app.Name}, dep) if errors.IsNotFound(err) { dep buildDeployment(app) if err : r.Create(ctx, dep); err ! nil { return ctrl.Result{}, err } return ctrl.Result{}, nil } if !reflect.DeepEqual(dep.Spec.Template.Spec.Containers[0].Image, app.Spec.Image) { dep.Spec.Template.Spec.Containers[0].Image app.Spec.Image if err : r.Update(ctx, dep); err ! nil { return ctrl.Result{}, err } } app.Status.AvailableReplicas dep.Status.AvailableReplicas if err : r.Status().Update(ctx, app); err ! nil { return ctrl.Result{}, err } return ctrl.Result{}, nil }这个函数回答了前面所有原理问题它每次只拿到名字然后自己 Get它不关心事件类型它做了存在性判断的幂等创建它只做差异更新最后更新 Status让整个系统能感知进展。实际工程里ctrl.CreateOrUpdate能进一步简化创建和更新分支但底层逻辑和我上面手写的一致。我建议初学者至少手写一遍这种逻辑不要上来就依赖高级封装否则很难建立调谐的心智模型。3.4 打通生成链路make generate / manifests / installKubebuilder 项目里有个固定的开发循环我管它叫三遍 make# 1. 改了 Go 类型之后重新生成 DeepCopy 等代码 make generate # 2. 从 Go 类型生成 CRD/YAML 和 RBAC 清单 make manifests # 3. 把 CRD 安装到当前 kubeconfig 指向的集群 make install # 4. 本地跑控制器不打包镜像直接进程运行 make run这里有几个非常容易坑的细节改了api/v1下的字段make generate没跑CRD 里永远不会有新字段客户端可能一直报字段不识别。RBAC 权限不是自动发现的需要在 controller 的注释里写kubebuilder:rbac:groupsapps,resourcesdeployments,verbsget;list;watch;create;update;patch;delete然后make manifests才能把它生成到 RBAC 清单里。写漏了运行时会看到forbidden错误。make install只装 CRD不装 controller。只装 CRD 之后你手动创建 CR集群里不会有任何控制器响应这方便调试但也容易让人误以为代码没跑起来。如果要用镜像部署到集群还要走make docker-build和make deploy中间涉及镜像仓库地址的修改。本地调试阶段我强烈建议先make run日志直接打到终端省去镜像部署的调试成本。4. 模拟集群里的全链路调谐4.1 从提交一个 CR 开始理论讲完我们走一遍完整现场。假设我已经把MyApp的 CRDmake install装进了一个开发集群现在用户提交下面这个资源apiVersion: sample.example.io/v1 kind: MyApp metadata: name: myapp-sample spec: replicas: 2 image: nginx:1.24用户执行kubectl apply -f myapp.yaml时API Server 会做的事包括校验这个对象是否符合 CRD 的 schema比如replicas是不是整数、是否在允许范围内校验通过后写入 etcd返回创建成功。此刻用户视角是我建了一个 MyApp但对整个系统来说这只是一条期望状态被写入数据库的记录真正的大戏在控制器那边。4.2 事件如何流到 ReconcileCR 创建成功后控制器这边的链路大致是控制器进程内的 Informer 通过 Watch 监听到myapp-sample的 ADDED 事件事件被封装成一个reconcile.Request里面只有命名空间和名字请求进入 WorkQueuecontroller-runtime 的 worker goroutine 取出请求调用你的Reconcile(ctx, req)。这条链路里从提交 CR 到触发 Reconcile 往往只需要几十毫秒但这里有一个极其重要的设计点事件本身不带数据你的 Reconcile 需要在入口处自行读取资源最新状态。为什么要这么设计因为在事件入队到出队之间资源可能已经被修改多次事件携带的数据早已过期只有每次都读最新状态才能保证 controller 的行为始终基于当前事实而不是某次事件快照。另外要特别注意CR 的 Status 更新同样会产生事件。这会导致一个常见但正常的现象一次简单的创建操作Reconcile 会被触发多次这是控制循环的正常节奏不是 bug。4.3 Reconcile 内的实际操作逻辑我们来看那次 Reconcile 内部到底发生了什么。假设这是第一次被触发状态如下从缓存读取MyApp拿到spec.replicas2、spec.imagenginx:1.24去读同名Deployment结果 NotFound进入创建分支组装一个 Deployment 对象设置副本数 2、镜像 nginx:1.24、打上appmyapp-sample的标签同时设置 OwnerReference 指向这个 MyApp调用 Kubernetes API 创建 Deployment返回ctrl.Result{}Reconcile 结束。这里有一个细节值得展开。OwnerReference 是控制器 GC 的基石。创建子资源的时候设置好 OwnerReference之后如果 MyApp 被删除Kubernetes 的 GC 控制器会自动清理掉它拥有的 Deployment不需要你在控制器里写删除逻辑。不设 OwnerReference 的话用户删了 MyApp子资源就变成孤儿资源永远留在集群里。下一次 Reconcile 到来时Deployment 已经存在了代码进入 diff 分支副本数一致、镜像一致那就什么都不用更新然后把 Deployment 的可用副本数写到 MyApp 的 Status 里。用户此时执行kubectl get myapp就能看到AVAILABLE REPLICAS字段在变化。这就是 Status 作为对外呈现进展的意义。4.4 现场日志为什么一次操作会触发多次调谐我实际跑这个例子时控制台日志大致长这样INFO controller.myapp Reconciling MyApp {controller: myapp, request: default/myapp-sample} INFO controller.myapp Deployment not found, creating ... {controller: myapp, name: default/myapp-sample} INFO controller.myapp Reconcile succeeded {controller: myapp, request: default/myapp-sample} INFO controller.myapp Reconciling MyApp {controller: myapp, request: default/myapp-sample} INFO controller.myapp Deployment already exists, checking spec ... {controller: myapp, name: default/myapp-sample} INFO controller.myapp Updating status ... {controller: myapp, name: default/myapp-sample} INFO controller.myapp Reconcile succeeded {controller: myapp, request: default/myapp-sample}你可能会奇怪为什么同一个request出现两三次其实来源各不相同第一次是 MyApp 创建事件第二次是 Deployment 创建/更新事件触发——因为你Owns了 Deployment还有 Status 更新时MyApp 对象本身的 Update 事件又会被 Informer 捕获再次触发一次。三次互相叠加视觉上就像同一个逻辑跑了好多遍。这就是为什么我前面强调幂等如果 Reconcile 里写了无条件创建 Deployment它就会重复创建或者报 AlreadyExists如果你写了每次更新 Status 都重新计算并写一遍在高频事件下可能把 API Server 打得很厉害。正确做法是想清楚每个动作是否需要执行不需要就跳过需要就保证重复执行无副作用。调日志的时候我习惯在每个关键分支里显式打日志而不是只打Reconcile succeeded否则以后排查问题根本不知道哪一步走了弯路。5. 真实开发中最容易踩的坑5.1 Reconcile 被频繁触发要不要管我收到最多的疑问就是这个我的 Reconcile 怎么一秒被调用了十几次是不是写错了绝大多数情况这很正常。CR 创建、字段更新、Status 更新、子资源变化、resync都会触发。你的 Reconcile 本来就是被设计来反复执行的。但有一种异常频繁值得注意如果你的 Reconcile 里每次都会无条件更新 Status比如把当前时间戳写进 Status那么每次写入又变成一次新的 Update 事件形成无限自激循环——这是典型的自己触发自己。我在设计规范里要求团队Status 只在值发生变化时更新不要做无意义刷新。判断标准也很简单当前 Status 和新值是否一致不一致才写。另外MaxConcurrentReconciles参数决定同时跑多少个 worker默认是 1也就是说同一时间只有一个 Reconcile 在执行其余排队。如果你有大量 CR 且每个 Reconcile 很慢吞吐会感人。可以按需调大但要注意外部系统的压力。5.2 创建 CR 后 Reconcile 不执行这个问题的排查路径是固定的。我直接整理成速查表现象可能原因排查方法创建 CR 后控制器日志无任何输出controller 没注册进 Manager或没有监听该 GroupVersion检查 SetupWithManager 的 For 类型是否匹配日志里有 forbidden 错误RBAC 权限没配齐检查kubebuilder:rbac注释和生成的 RoleCRD 不存在或没装进当前集群装错了集群或忘跑 make installkubectl get crd myapps.sample.example.io本地代码访问了错误集群kubeconfig 指错kubectl cluster-info确认再make run事件已入队但 Reconcile 报错重试代码本身 panic 或依赖外部服务不可用看日志 stack trace先恢复依赖这里最容易忽略的一个坑是 Kustomize 的命名空间。make deploy默认部署到config/manager/manager.yaml里指定的 namespace如果 RBAC 清单只在那个 namespace 下生效跨 namespace 的 CR 可能被拒绝。早期调试直接用make run能避开不少此类问题。5.3 删除一直被 Terminating如果你的 CRD 里定义了一个 Finalizer用户在删除 CR 时资源不会立刻消失而是进入 Terminating 状态直到 Finalizer 被移除。这个机制的本意是让控制器有机会在资源被真正删除前做清理工作释放云磁盘、通知外部系统、备份配置等。问题在于很多初学者定义了 Finalizer 却忘了在 Reconcile 里处理删除请求结果就是用户kubectl delete之后那个 CR 永远卡在 Terminating像一具没有遗嘱的躯壳。正确姿势是在 Reconcile 开头检查DeletionTimestampif !app.DeletionTimestamp.IsZero() { // 1. 清理外部资源删除云磁盘、通知上游系统等 // 2. 确认清理完毕之后移除 finalizer controllerutil.RemoveFinalizer(app, sample.example.io/finalizer) if err : r.Update(ctx, app); err ! nil { return ctrl.Result{}, err } return ctrl.Result{}, nil }这又是一个控制循环打底的典型场景删除不是一次性操作而是一个反复尝试清理直到清理完成才放行删除的循环过程。如果清理失败Reconcile 返回 errorWorkQueue 会退避重试直到成功。我在实践里吃过不少次这个教训现在每写一个带 Finalizer 的 CRD都会先把这个删除分支补好。5.4 本地调试的正确姿势本地调试我推荐两层策略。第一层是单元测试Kubebuilder 生成的suite_test.go里自带 envtest 环境会在你本地启动一个临时的 API Server不依赖真实集群。你可以用它做内存级别的快速验证比如创建 CR、调用 Reconcile、断言子资源是否被创建。这类测试跑得飞快适合在提交代码前安全网。第二层是真实开发集群验验。我会准备一个 kind 或 minikube 集群make install把 CRD 装进去再make run直接本地跑 controller。好处是日志实时、断点方便、不需要构建镜像。等逻辑稳定之后才走make docker-build和make deploy部署到共享环境。调试日志级别也值得掌握。controller-runtime 支持-v参数调整日志详细程度开 development 模式时默认日志里会带源码文件和行号。我需要看事件细节时会把-v开到 4 甚至 5正常跑只留 1 级。日志写得太少不利于排障太多又淹没关键信息我个人的标准是每个关键分支打一行包含资源名和判断原因比如Deployment not found, creating、Spec changed, updating image。5.5 三条我在实践中沉淀的设计红线最后分享几条我用真金白银换来的设计红线。第一条Reconcile 永远基于当前读到的状态做决策不基于我上一步做了什么。不要在控制器里维护内存变量来记住上次创建了 Deployment因为这个进程可能崩溃重启变量全部清空。每次循环都把现状重读一遍这是唯一可靠的。第二条所有外部副作用都要做幂等和重试准备。你的 Reconcile 可能因为 WorkQueue 重试、多个 worker 并发、leader 切换而重复执行。调用支付类、发消息类、改 DNS 类的外部 API 时必须先查后做或者带上幂等键否则一次故障重试就会造成重复扣款或重复通知。第三条Spec 是期望输入Status 是事实输出不要把临时推断结果塞进 Status。我见过有人把预计扩容数量这种中间计算值写进 Status导致用户分不清哪些是事实、哪些是意图。Status 应该忠实地反映当前状态和最近一次成败至于计算过程留在代码局部变量里就够了。这三条如果从一开始就遵守Operator 的坑能少踩一大半。
如果你已经在 Kubernetes 上部署过几次应用大概率遇到过这种情况Deployment 挂了三副本其中一副本被 node 驱逐过一会儿它自己又起来了——这是内置控制器在做心愿达成但你要是部署的是一个有状态的东西比如一套数据库集群、一套分布式缓存升级要先备份、故障要自动切换、扩容不是简单加一个 Pod——Kubernetes 就不管了。过去大家靠人肉运维靠脚本靠 cron维护成本极高而且容易漏。后来社区形成了更体系化的做法把运维逻辑写成一个常驻进程让 Kubernetes 用声明式的方式驱动它这个模式就是 kubernetes operator。而 kubebuilder 是目前最主流的 Operator 开发框架底层大量封装了 controller-runtime 的机制。这篇文章我先不展开脚手架命令先把 Operator 的工作原理讲透。因为我在实际带团队时反复发现很多人会用 kubebuilder 生成项目能跑起来但 Reconcile 为什么会被调用、为什么自己改了状态又触发一次、Informer 和 WorkQueue 到底在里面扮演什么角色这些不搞清楚写出来的东西只能是会调 API 的脚本一旦遇到复杂状态就失控。这篇内容适合已经能熟练部署 Deployment、Service、Pod正准备进入自定义控制器开发的读者原理通了后面任何框架都只是壳。1. Operator 到底在解决什么问题1.1 Kubernetes 天生就是一个声明式自动巡航系统Kubernetes 自己的架构就是大规模控制器集群。你kubectl apply一个 Deployment 文件里面写的是我要三个副本、镜像 nginx:1.24、端口 80这是你的期望状态。API Server 负责把这份声明存进 etcd然后一堆控制器就开始盯着它干活Deployment 控制器发现 ReplicaSet 数量不对就去创建ReplicaSet 控制器发现 Pod 数量不对就去创建 Pod调度器发现 Pod 还没落节点给它选一台机器kubelet 发现节点上有 Pod 没启动容器就拉镜像启动。这一整套动作没有谁在命令谁每个组件都只做一件事读当前状态对比期望状态如果有差距就执行动作让现状靠近期望。你用户侧只负责声明不负责指挥。这就是声明式 API 和控制循环的威力——系统里任何一步被干扰、被打断、被删掉控制器都会在下一轮循环里把它纠正回来。这也是理解 Operator 的第一块基石控制器不是执行一次任务而是永远在奔向期望状态的路上。你写一个控制器本质是在给 Kubernetes 增加一种新的纠偏能力。1.2 Controller 与 Operator从内置逻辑到业务逻辑Kubernetes 内置控制器很全能但只局限于它认识的内置资源Deployment、Service、ConfigMap、Ingress 这些。一旦你说我要一个生产可用的数据库集群包含 5 个节点、一主多从、自动故障切换、每天凌晨备份、升级前先冻结写入Kubernetes 就听不懂了。这时候需要两样东西配合CRDCustom Resource Definition让 Kubernetes 认识你的新资源类型。你定义一个DatabaseCluster里面有spec.replicas、spec.version、spec.backup.enabled等字段。从此kubectl get databaseclusters也能用了。Controller / Operator真正实现如何把这个 DatabaseCluster 落到现实里。它 watch 用户创建的数据库集群实例然后负责去创建 StatefulSet、Service、备份 CronJob监控故障执行切换更新状态。Operator 这个词和 Controller 基本是同一个东西只是更强调业务领域知识。举个例子Deployment 控制器像是标准家政服务只做保证有 N 份这个通用约定而 Operator 像是专属管家它懂你家每一件电器的脾气——哪个要先备份再升级哪个故障了要切换到备机哪个挂了你得先通知业务方。它把人类的运维知识变成了代码里的判断逻辑。所以我的理解是Operator CRD扩展资源模型 Controller控制循环 领域运维知识。三者缺一个都不是完整意义上的 Operator。1.3 哪些场景才值得写 Operator这部分我必须泼点冷水。不是所有东西都值得写成 Operator。我见过有人把创建一个 Deployment Service这种五分钟手工活也封装成 Operator结果维护成本比手动 apply 高了一个数量级。真正值得写 Operator 的信号我总结为这四条资源有生命周期管理需求安装、升级、备份、恢复、删除清理每一步都不是单纯 apply 能搞定的。存在可固化的故障补救规则比如主节点失联超过 30 秒把备节点提升为主节点这种明确规则值得让程序反复执行。需要和外部系统联动需要去云平台创建负载均衡、存储卷、DNS 记录然后等待外部状态就绪。需要根据业务状态自动扩缩容或配置变更单纯 HPA 不够要从业务指标决定拓扑变化。如果是部署一次静态 YAMLHelm Chart 就够用了如果是周期性清理任务CronJob 更合适。写 Operator 意味着你要长期维护一个控制器的正确性、权限、版本兼容性这是一笔不小的工程成本。先确认痛点是重复性强、规则明确、人工容易出错再动手。2. 控制循环Operator 的心脏2.1 期望状态、实际状态与调谐Reconcile控制循环这个词听起来高大上其实你可以把它想成空调的恒温器你设了 24 度这是期望状态房间里实际 28 度这是实际状态空调一直读温度计温度高了制冷、低了加热直到接近 24 度它就进入低频待机哪天窗户开了温度又升上去它继续工作。人设定完温度之后就不需要反复操作了。Kubernetes 的控制循环完全一样。用户定义的 CR 的spec就是24 度集群里真实存在的 Deployment、Pod、Service、外部云资源就是实际温度控制器里的核心函数Reconcile就是温度比较和调整逻辑。它做三件事先读期望状态从 CR 的 spec 里拿、再读实际状态从集群里查、然后执行动作让两者尽量一致。这里有个新手最容易误解的点Reconcile 不是事件回调不是用户创建了 CR 我执行一次就完事。它是被反复触发的创建触发、更新触发、子资源变化触发、甚至什么都不发生控制器还会周期性回来检查一遍。这在机制上叫 resync。为什么要这样因为集群状态随时可能被别的东西改变只有周期性地重新对比才能保证声明最终被实现。理解这一点之后你就不会写只在创建时做初始化这种控制器了。2.2 从 Watch 到 Diff 到 Act 到 Update 的标准四步控制循环的每次执行拆开看都是固定四步Watch监听控制器先要订阅感兴趣的资源。至少包含它自己管理的 CRD 类型通常还会监听它创建出来的子资源比如 Deployment、Pod。任何相关的增删改都会变成一次入队信号。Diff对比拿到资源后读取 spec 里的期望值再去查实际状态。实际的 Deployment 存在吗副本数对吗镜像版本对吗状态里有没有异常Act执行根据差异决定动作。没创建就创建规格不一致就更新资源要删除就清理。如果涉及外部系统这一步通常还包含调用云 API、等待结果。Update更新状态把这次循环的结果写到 CR 的status字段里。这一步很关键因为用户和上层系统是通过 status 来判断当前进展的。而且 status 一更新又会触发 Watch开启下一轮 Reconcile。我给你画一个简化但不失真的节奏假设控制器管理一个MyApp资源它期望创建 2 个副本。第一次 Reconcile 发现 Deployment 不存在于是创建第二次 Reconcile 发现 Deployment 存在但可用副本还是 0于是什么都不改把 status.availableReplicas 更新为 0第三次 Reconcile 发现 Deployment 可用副本为 1继续更新状态直到可用副本变成 2status 写入 2此时期望和实际一致Reconcile 进入观察模式。每次循环本身都很廉价关键是循环逻辑必须可以反复执行而且每次执行结果一致。2.3 Informer 机制为什么不能直接打 API那你可能会想循环里直接调 Kubernetes API 把资源全部 List 一遍不就行了小规模没问题规模一大就完蛋。比如集群里有 500 个MyApp每个MyApp又管理 3 个子资源如果每 10 秒全量 List 一次API Server 会被打爆。所以 controller-runtime 用了 Informer 机制。它做的事情可以理解成订阅制而不是轮询制首次启动时做一次 List拿到全量对象建立本地缓存之后通过 Watch 监听增量事件不停更新缓存所有读操作优先走本地缓存只有写操作才直接请求 API Server如果 Watch 连接断了Informer 会重新 List 兜底保证缓存不出错。另外Watch 到的原始事件不会直接调你的 Reconcile而是先丢进一个 WorkQueue。WorkQueue 会对相同资源的多个事件做去重合并——短时间内同一个资源变化了十次队列里可能只留一个请求处理失败还会指数退避重试。这就是为什么 Reconcile 收到的请求里只有一个namespace/name而不是完整的事件数据。有个隐含设计很多人没意识到正因为 Reconcile 只拿到一个对象名字它必须重新去读 API所以就算事件丢了、队列出错了下一轮循环也能从当前状态重新收敛。这是整个控制器模型健壮性的根源——它不依赖事件传输不丢而依赖每次重算都基于当前事实。2.4 事件、队列与幂等设计的必然性理解了队列的合并与退避你就会明白一个结论你永远不知道这一次 Reconcile 究竟是因为什么被触发的。可能是创建可能是状态更新可能是子资源变化也可能是周期性 resync。控制器代码里如果写了if 事件创建这种思路一开始就错了。正确姿势是不管因为什么被触发每次都完整执行读 spec、读现状、做 diff、执行动作。具体到一个细节你创建完 Deployment 后要不要立刻在同一个 Reconcile 里等它就绪不要。因为 Deployment 的可用状态变化会再次触发你的 Reconcile你只需要在下一次循环里检查它就行。这种各管一段、循环推进的设计让整个系统几乎不需要锁也不需要复杂的编排状态。我早期写控制器踩过一个典型的坑为了优化性能把创建 Deployment 之后的等待逻辑放在同一个 Reconcile 里死循环探测结果一方面阻塞了 worker 线程另一方面一旦中途失败WorkQueue 重试时又会重复创建。后来我终于明白控制循环的正确姿势是一步到位然后回来看结果而不是一次调完所有步骤。你每一步都应该是幂等的创建前先查存在不存在更新前先比字段一不一样外部 API 调用要做去重和重试准备。3. Kubebuilder把控制器原理工程化3.1 脚手架帮我们建了什么原理归原理从零写一个控制器要处理大量重复工程Informer 初始化、WorkQueue 创建、Leader 选举、指标暴露、Webhook 服务、RBAC 清单……Kubebuilder 的价值就是把这些全部固化成语料和代码骨架让开发者只专注于 CRD 类型和 Reconcile 逻辑。我用kubebuilder init和kubebuilder create api生成一个项目后核心目录大概长这样路径作用你需要关心的程度api/v1/CRD 的 Go 类型定义、DeepCopy 方法高你的资源字段在这里定义controllers/控制器实现Reconcile 逻辑的所在地很高核心业务代码config/crd/从 Go 类型生成的 CRD YAML 清单中主要靠 make manifests 生成config/rbac/控制器操作各类资源所需权限高写错了直接 403main.go组装 Manager、注册 Controller、启动 Webhook低默认代码基本够用Makefile封装 generate/manifests/install/run 等命令高开发循环都靠它其中main.go里的 Manager 是进程骨架它把所有组件缝合在一起缓存、客户端、控制器、Webhook、健康检查、指标端口。你写的每个控制器都要注册到这个 Manager 上Manager 启动后才会拉起对应 worker 循环。3.2 编写 CRD定义属于你的资源在 Kubebuilder 里资源类型是用 Go struct 定义的。一般分为 Spec 和 Status 两部分。我习惯给团队解释成Spec 是用户填的订单Status 是控制器写的发货状态。用户只写订单控制器不断更新发货状态两边互不干扰。下面是一个最小示例假设我们要定义一个叫MyApp的资源type MyAppSpec struct { Replicas int32 json:replicas Image string json:image } type MyAppStatus struct { AvailableReplicas int32 json:availableReplicas Phase string json:phase,omitempty } type MyApp struct { metav1.TypeMeta json:,inline metav1.ObjectMeta json:metadata,omitempty Spec MyAppSpec json:spec,omitempty Status MyAppStatus json:status,omitempty }定义好类型之后make generate会生成 DeepCopy 方法make manifests会从 Go 类型生成 CRD 的 YAML。生成的 YAML 里会体现字段的校验规则比如apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: myapps.sample.example.io spec: group: sample.example.io versions: - name: v1 schema: openAPIV3Schema: properties: spec: properties: replicas: format: int32 type: integer image: type: string type: object status: properties: availableReplicas: format: int32 type: integer type: object scope: Namespaced想做必填校验、枚举值、正则也是通过 Go 类型上的kubebuilder:validation注释来实现。这里提醒新手一件事版本字段和 API group 一旦发布改起来代价很高。不要一上来就搞 v2 多版本支持先老老实实 v1 单版本等用户真多了再考虑版本转换。3.3 编写 ControllerReconcile 函数就是全部真相Kubebuilder 生成的 controller 骨架里你真正要写的东西其实就一个函数外加一个SetupWithManager方法。SetupWithManager做的事情就是向 Manager 声明我关注MyApp主资源同时关注我做出来的Deployment子资源。func (r *MyAppReconciler) SetupWithManager(mgr ctrl.Manager) error { return ctrl.NewControllerManagedBy(mgr). For(samplev1.MyApp{}). Owns(appsv1.Deployment{}). Complete(r) }这段代码揭示的原理是For声明主资源Owns声明子资源。一旦MyApp变化或者它拥有的Deployment变化事件都会进入同一个 WorkQueue最终都会调到Reconcile。而Reconcile函数长这样func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) { var app samplev1.MyApp if err : r.Get(ctx, req.NamespacedName, app); err ! nil { return ctrl.Result{}, client.IgnoreNotFound(err) } dep : appsv1.Deployment{} err : r.Get(ctx, types.NamespacedName{Namespace: app.Namespace, Name: app.Name}, dep) if errors.IsNotFound(err) { dep buildDeployment(app) if err : r.Create(ctx, dep); err ! nil { return ctrl.Result{}, err } return ctrl.Result{}, nil } if !reflect.DeepEqual(dep.Spec.Template.Spec.Containers[0].Image, app.Spec.Image) { dep.Spec.Template.Spec.Containers[0].Image app.Spec.Image if err : r.Update(ctx, dep); err ! nil { return ctrl.Result{}, err } } app.Status.AvailableReplicas dep.Status.AvailableReplicas if err : r.Status().Update(ctx, app); err ! nil { return ctrl.Result{}, err } return ctrl.Result{}, nil }这个函数回答了前面所有原理问题它每次只拿到名字然后自己 Get它不关心事件类型它做了存在性判断的幂等创建它只做差异更新最后更新 Status让整个系统能感知进展。实际工程里ctrl.CreateOrUpdate能进一步简化创建和更新分支但底层逻辑和我上面手写的一致。我建议初学者至少手写一遍这种逻辑不要上来就依赖高级封装否则很难建立调谐的心智模型。3.4 打通生成链路make generate / manifests / installKubebuilder 项目里有个固定的开发循环我管它叫三遍 make# 1. 改了 Go 类型之后重新生成 DeepCopy 等代码 make generate # 2. 从 Go 类型生成 CRD/YAML 和 RBAC 清单 make manifests # 3. 把 CRD 安装到当前 kubeconfig 指向的集群 make install # 4. 本地跑控制器不打包镜像直接进程运行 make run这里有几个非常容易坑的细节改了api/v1下的字段make generate没跑CRD 里永远不会有新字段客户端可能一直报字段不识别。RBAC 权限不是自动发现的需要在 controller 的注释里写kubebuilder:rbac:groupsapps,resourcesdeployments,verbsget;list;watch;create;update;patch;delete然后make manifests才能把它生成到 RBAC 清单里。写漏了运行时会看到forbidden错误。make install只装 CRD不装 controller。只装 CRD 之后你手动创建 CR集群里不会有任何控制器响应这方便调试但也容易让人误以为代码没跑起来。如果要用镜像部署到集群还要走make docker-build和make deploy中间涉及镜像仓库地址的修改。本地调试阶段我强烈建议先make run日志直接打到终端省去镜像部署的调试成本。4. 模拟集群里的全链路调谐4.1 从提交一个 CR 开始理论讲完我们走一遍完整现场。假设我已经把MyApp的 CRDmake install装进了一个开发集群现在用户提交下面这个资源apiVersion: sample.example.io/v1 kind: MyApp metadata: name: myapp-sample spec: replicas: 2 image: nginx:1.24用户执行kubectl apply -f myapp.yaml时API Server 会做的事包括校验这个对象是否符合 CRD 的 schema比如replicas是不是整数、是否在允许范围内校验通过后写入 etcd返回创建成功。此刻用户视角是我建了一个 MyApp但对整个系统来说这只是一条期望状态被写入数据库的记录真正的大戏在控制器那边。4.2 事件如何流到 ReconcileCR 创建成功后控制器这边的链路大致是控制器进程内的 Informer 通过 Watch 监听到myapp-sample的 ADDED 事件事件被封装成一个reconcile.Request里面只有命名空间和名字请求进入 WorkQueuecontroller-runtime 的 worker goroutine 取出请求调用你的Reconcile(ctx, req)。这条链路里从提交 CR 到触发 Reconcile 往往只需要几十毫秒但这里有一个极其重要的设计点事件本身不带数据你的 Reconcile 需要在入口处自行读取资源最新状态。为什么要这么设计因为在事件入队到出队之间资源可能已经被修改多次事件携带的数据早已过期只有每次都读最新状态才能保证 controller 的行为始终基于当前事实而不是某次事件快照。另外要特别注意CR 的 Status 更新同样会产生事件。这会导致一个常见但正常的现象一次简单的创建操作Reconcile 会被触发多次这是控制循环的正常节奏不是 bug。4.3 Reconcile 内的实际操作逻辑我们来看那次 Reconcile 内部到底发生了什么。假设这是第一次被触发状态如下从缓存读取MyApp拿到spec.replicas2、spec.imagenginx:1.24去读同名Deployment结果 NotFound进入创建分支组装一个 Deployment 对象设置副本数 2、镜像 nginx:1.24、打上appmyapp-sample的标签同时设置 OwnerReference 指向这个 MyApp调用 Kubernetes API 创建 Deployment返回ctrl.Result{}Reconcile 结束。这里有一个细节值得展开。OwnerReference 是控制器 GC 的基石。创建子资源的时候设置好 OwnerReference之后如果 MyApp 被删除Kubernetes 的 GC 控制器会自动清理掉它拥有的 Deployment不需要你在控制器里写删除逻辑。不设 OwnerReference 的话用户删了 MyApp子资源就变成孤儿资源永远留在集群里。下一次 Reconcile 到来时Deployment 已经存在了代码进入 diff 分支副本数一致、镜像一致那就什么都不用更新然后把 Deployment 的可用副本数写到 MyApp 的 Status 里。用户此时执行kubectl get myapp就能看到AVAILABLE REPLICAS字段在变化。这就是 Status 作为对外呈现进展的意义。4.4 现场日志为什么一次操作会触发多次调谐我实际跑这个例子时控制台日志大致长这样INFO controller.myapp Reconciling MyApp {controller: myapp, request: default/myapp-sample} INFO controller.myapp Deployment not found, creating ... {controller: myapp, name: default/myapp-sample} INFO controller.myapp Reconcile succeeded {controller: myapp, request: default/myapp-sample} INFO controller.myapp Reconciling MyApp {controller: myapp, request: default/myapp-sample} INFO controller.myapp Deployment already exists, checking spec ... {controller: myapp, name: default/myapp-sample} INFO controller.myapp Updating status ... {controller: myapp, name: default/myapp-sample} INFO controller.myapp Reconcile succeeded {controller: myapp, request: default/myapp-sample}你可能会奇怪为什么同一个request出现两三次其实来源各不相同第一次是 MyApp 创建事件第二次是 Deployment 创建/更新事件触发——因为你Owns了 Deployment还有 Status 更新时MyApp 对象本身的 Update 事件又会被 Informer 捕获再次触发一次。三次互相叠加视觉上就像同一个逻辑跑了好多遍。这就是为什么我前面强调幂等如果 Reconcile 里写了无条件创建 Deployment它就会重复创建或者报 AlreadyExists如果你写了每次更新 Status 都重新计算并写一遍在高频事件下可能把 API Server 打得很厉害。正确做法是想清楚每个动作是否需要执行不需要就跳过需要就保证重复执行无副作用。调日志的时候我习惯在每个关键分支里显式打日志而不是只打Reconcile succeeded否则以后排查问题根本不知道哪一步走了弯路。5. 真实开发中最容易踩的坑5.1 Reconcile 被频繁触发要不要管我收到最多的疑问就是这个我的 Reconcile 怎么一秒被调用了十几次是不是写错了绝大多数情况这很正常。CR 创建、字段更新、Status 更新、子资源变化、resync都会触发。你的 Reconcile 本来就是被设计来反复执行的。但有一种异常频繁值得注意如果你的 Reconcile 里每次都会无条件更新 Status比如把当前时间戳写进 Status那么每次写入又变成一次新的 Update 事件形成无限自激循环——这是典型的自己触发自己。我在设计规范里要求团队Status 只在值发生变化时更新不要做无意义刷新。判断标准也很简单当前 Status 和新值是否一致不一致才写。另外MaxConcurrentReconciles参数决定同时跑多少个 worker默认是 1也就是说同一时间只有一个 Reconcile 在执行其余排队。如果你有大量 CR 且每个 Reconcile 很慢吞吐会感人。可以按需调大但要注意外部系统的压力。5.2 创建 CR 后 Reconcile 不执行这个问题的排查路径是固定的。我直接整理成速查表现象可能原因排查方法创建 CR 后控制器日志无任何输出controller 没注册进 Manager或没有监听该 GroupVersion检查 SetupWithManager 的 For 类型是否匹配日志里有 forbidden 错误RBAC 权限没配齐检查kubebuilder:rbac注释和生成的 RoleCRD 不存在或没装进当前集群装错了集群或忘跑 make installkubectl get crd myapps.sample.example.io本地代码访问了错误集群kubeconfig 指错kubectl cluster-info确认再make run事件已入队但 Reconcile 报错重试代码本身 panic 或依赖外部服务不可用看日志 stack trace先恢复依赖这里最容易忽略的一个坑是 Kustomize 的命名空间。make deploy默认部署到config/manager/manager.yaml里指定的 namespace如果 RBAC 清单只在那个 namespace 下生效跨 namespace 的 CR 可能被拒绝。早期调试直接用make run能避开不少此类问题。5.3 删除一直被 Terminating如果你的 CRD 里定义了一个 Finalizer用户在删除 CR 时资源不会立刻消失而是进入 Terminating 状态直到 Finalizer 被移除。这个机制的本意是让控制器有机会在资源被真正删除前做清理工作释放云磁盘、通知外部系统、备份配置等。问题在于很多初学者定义了 Finalizer 却忘了在 Reconcile 里处理删除请求结果就是用户kubectl delete之后那个 CR 永远卡在 Terminating像一具没有遗嘱的躯壳。正确姿势是在 Reconcile 开头检查DeletionTimestampif !app.DeletionTimestamp.IsZero() { // 1. 清理外部资源删除云磁盘、通知上游系统等 // 2. 确认清理完毕之后移除 finalizer controllerutil.RemoveFinalizer(app, sample.example.io/finalizer) if err : r.Update(ctx, app); err ! nil { return ctrl.Result{}, err } return ctrl.Result{}, nil }这又是一个控制循环打底的典型场景删除不是一次性操作而是一个反复尝试清理直到清理完成才放行删除的循环过程。如果清理失败Reconcile 返回 errorWorkQueue 会退避重试直到成功。我在实践里吃过不少次这个教训现在每写一个带 Finalizer 的 CRD都会先把这个删除分支补好。5.4 本地调试的正确姿势本地调试我推荐两层策略。第一层是单元测试Kubebuilder 生成的suite_test.go里自带 envtest 环境会在你本地启动一个临时的 API Server不依赖真实集群。你可以用它做内存级别的快速验证比如创建 CR、调用 Reconcile、断言子资源是否被创建。这类测试跑得飞快适合在提交代码前安全网。第二层是真实开发集群验验。我会准备一个 kind 或 minikube 集群make install把 CRD 装进去再make run直接本地跑 controller。好处是日志实时、断点方便、不需要构建镜像。等逻辑稳定之后才走make docker-build和make deploy部署到共享环境。调试日志级别也值得掌握。controller-runtime 支持-v参数调整日志详细程度开 development 模式时默认日志里会带源码文件和行号。我需要看事件细节时会把-v开到 4 甚至 5正常跑只留 1 级。日志写得太少不利于排障太多又淹没关键信息我个人的标准是每个关键分支打一行包含资源名和判断原因比如Deployment not found, creating、Spec changed, updating image。5.5 三条我在实践中沉淀的设计红线最后分享几条我用真金白银换来的设计红线。第一条Reconcile 永远基于当前读到的状态做决策不基于我上一步做了什么。不要在控制器里维护内存变量来记住上次创建了 Deployment因为这个进程可能崩溃重启变量全部清空。每次循环都把现状重读一遍这是唯一可靠的。第二条所有外部副作用都要做幂等和重试准备。你的 Reconcile 可能因为 WorkQueue 重试、多个 worker 并发、leader 切换而重复执行。调用支付类、发消息类、改 DNS 类的外部 API 时必须先查后做或者带上幂等键否则一次故障重试就会造成重复扣款或重复通知。第三条Spec 是期望输入Status 是事实输出不要把临时推断结果塞进 Status。我见过有人把预计扩容数量这种中间计算值写进 Status导致用户分不清哪些是事实、哪些是意图。Status 应该忠实地反映当前状态和最近一次成败至于计算过程留在代码局部变量里就够了。这三条如果从一开始就遵守Operator 的坑能少踩一大半。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
