用controller-runtime而非手写client-go，因其封装了事件重试、OwnerReference清理、Finalizer协调等细节，仅需实现Reconcile方法；需注意Status单独更新、命名空间限制、Finalizer触发条件及命名规范。
为什么用 controller-runtime 而不是手写 client-go？
因为直接调 client-go 的 Informers + Workqueue 容易漏掉事件重试、OwnerReference 自动清理、Finalizer 协调这些细节，controller-runtime 把它们封装成可组合的 Reconciler 接口和 Manager 生命周期管理。你真正要写的逻辑，其实就一个 Reconcile 方法。
常见错误现象：Reconcile 返回 nil 但资源状态没更新，或者 Finalizer 不触发 —— 很可能是因为没调 client.Update 或忘了在 Update 前先 DeepCopy 对象（否则会因引用修改导致缓存污染）。
-
Reconcile必须返回ctrl.Result{}和error；返回nil, nil表示成功且不重试；返回ctrl.Result{RequeueAfter: time.Second}才会延迟重入 - 不要在
Reconcile里做阻塞 IO（如 HTTP 请求未设 timeout），这会卡住整个 controller 的 worker 队列 -
client.Get和client.List默认走缓存；需要实时数据时加client.Raw或用client.SubResource("status").Get
Reconcile 函数里怎么安全地更新 Status 字段？
CRD 的 status 子资源必须单独更新，不能和 spec 一起 Update，否则 K8s API Server 会报错 Invalid: status.subresources.status。controller-runtime 提供了 client.Status().Update 方法专门干这事。
使用场景：当控制器完成某个异步动作（比如创建了底层 Deployment），需要把当前状态（如 Ready: true、ObservedGeneration）写回 status 字段。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 必须先用
client.Get拿到最新对象，再修改其Status字段，最后调client.Status().Update(ctx, obj) - 如果同时更新
spec和status，两个操作要分开：先Updatespec，再Status().Update；顺序反了会失败 - 注意并发：多个 Reconcile 实例可能同时操作同一个对象，Status 更新失败时通常应重试（返回
error即可，框架自动重入）
如何让控制器只监听特定命名空间，而不是集群范围？
默认 Manager 启动的 Cache 是集群范围的，监听所有命名空间下的自定义资源。想限制作用域，得在 Builder 阶段指定 Namespaced，并在 Manager 初始化时传入 cache.Options{Namespace: "my-ns"}。
参数差异：Namespaced 是针对某类资源的监听范围，cache.Options.Namespace 是整个 cache 的默认命名空间过滤 —— 二者要一致，否则 Watch 可能收不到事件或 panic。
- 注册 controller 时用
ctrl.NewControllerManagedBy(mgr).For(&myv1.MyResource{}).Namespaced() - 启动
mgr时加cache.Options{Namespace: os.Getenv("WATCH_NAMESPACE")}，环境变量可从 Pod 的serviceaccount自动注入 - 如果 CRD 本身是
scope: Cluster，却强行设Namespace，会报错no matches for kind—— 这时候只能删掉cache.Options.Namespace，改用 labelSelector 过滤
Finalizer 不生效或被跳过，常见原因是什么？
Finalizer 是 CRD 删除前的“钩子”，但只有当对象的 deletionTimestamp 非空、且 finalizer 列表里包含你的值时，Reconcile 才会被持续调用直到 finalizer 清空。很多人写了 finalizer 却没看到它执行，本质是没检查 obj.DeletionTimestamp != nil 这个前提。
性能影响：Finalizer 逻辑如果失败，会不断重试，可能拖慢整个队列。建议加简单幂等判断（比如检查底层资源是否已不存在）。
- 添加 finalizer 要在对象创建后首次 Reconcile 时做：
obj.Finalizers = append(obj.Finalizers, "mycompany.com/my-finalizer")，然后client.Update - 删除 finalizer 必须在所有清理工作完成后，且要先
Get最新对象，再从Finalizers切片中移除对应字符串，再Update - 不要在 finalizer 清理逻辑里调
client.Delete后立刻 return；K8s 不保证底层资源立即消失，需轮询确认后再清 finalizer
容易被忽略的一点：Finalizer 名字必须符合 DNS 子域名格式（小写字母、数字、连字符、点），否则 API Server 会拒绝更新，但错误信息藏在 admission webhook 日志里，控制器日志只显示 Update failed。
