controller-runtime是最主流轻量Go SDK，封装client-go复杂性但保留事件与业务控制权；需注册client、manager、reconciler三组件，CRD类型须提前注册Scheme，监听资源需For()后调Complete()，Reconcile应幂等快速，避免阻塞与孤儿资源，本地调试需等待cache同步。
controller-runtime 是当前最主流、最轻量的 Go SDK，它封装了 client-go 的底层复杂性（比如 Informer 启动、Workqueue 管理、重试逻辑），但保留你对事件和业务逻辑的完全控制权。直接用它起步，别从零手写 Reflector 或 Indexer。
Reconcile 函数里怎么安全读写自定义资源
Reconcile 是控制器的核心入口，签名固定为：
func (r *MyReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
常见错误是拿到对象后直接改字段再 Update()，这在并发场景下大概率触发 resourceVersion conflict 错误。
- 优先使用
client.Patch()+client.MergeFrom()：只提交变更字段，天然避开乐观锁冲突 - 如果必须全量更新，得包一层
retry.RetryOnConflict，否则第一次失败就退出 - 所有错误必须显式检查：
if err != nil { return ctrl.Result{}, err }；特别注意client.IgnoreNotFound(err)处理不存在的情况，避免无限重试 - 更新
Status子资源时，必须用r.Status().Update(ctx, obj)，不能直接改 struct 再Update()，否则 API Server 会返回Invalid: status.subresources.status
SetupWithManager 里注册监听时容易漏的关键步骤
控制器默认不监听任何资源，必须显式声明。例如监听自定义 CR：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
func (r *MyReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&myv1.MyResource{}). // 必须注册类型
Complete(r)
}这里有两个高频坑：
- 只调
For()不够，必须接Complete()，否则 Informer 不启动，日志里看不到Starting workers，也收不到事件 -
For(&myv1.MyResource{})前，必须确保该类型已注册进 Scheme：- 在
main.go初始化时调用schemeBuilder.Register(&myv1.MyResource{}, &myv1.MyResourceList{}) - 并提前加载基础 Scheme：
clientgoscheme.AddToScheme(scheme)和apiextensionsv1.AddToScheme(scheme) - 否则启动时 panic：
no kind "MyResource" is registered for version "mygroup/v1"
- 在
本地调试前必须跑通的三件事
make run 卡住或报错，90% 是因为以下三件事没做：
- 先
make install：把 CRD 安装到集群，否则mgr.GetClient().Get()查不到自定义资源 - 再
make deploy（或至少kubectl apply -f config/rbac/）：确保 RBAC 包含对目标资源的get/list/watch权限；漏掉watch就不会触发Reconcile - 本地调试建议加
ENABLE_WEBHOOKS=false：避免证书问题干扰，Webhook 开启后需额外运行make cert-manager和make deploy
Reconcile 循环本身要快、幂等、无阻塞，但真正难的是初始化阶段——Scheme 注册、CRD 安装、RBAC 权限、缓存同步状态，这几步出错时往往没有明确报错，只表现为“没反应”。调试时先盯紧 manager 启动日志里有没有 Starting workers 和 Syncing cache，没有就说明卡在前面某一步。
