operator sdk初始化失败主因是go模块未启用或kubebuilder版本不兼容；reconcile中无法获取pod日志因client.client默认走cache，需用corev1clientset异步调用；crd升级需配置conversion webhook；reconcile不触发多因ownerreference uid错误或finalizer未清理。
Operator SDK初始化失败：kubebuilder init报错
新建项目时卡在 kubebuilder init，常见原因是 Go 模块未启用或 kubebuilder 版本与 Kubernetes API 不兼容。SDK v1.x（基于 kubebuilder v2）要求 Go 1.16+ 且必须开启 GO111MODULE=on；v2+（kubebuilder v3）则强制依赖 Go 1.19+ 和 go.work 支持。
- 执行前先确认：
go version、echo $GO111MODULE，若为空则运行export GO111MODULE=on - 用
kubebuilder version查版本，v3.x 要搭配operator-sdk init --plugins=go/v4，别混用 v2 插件 - 若提示
failed to create CRD: no matches for kind "CustomResourceDefinition"，说明 kubectl 或 controller-runtime 版本太低，检查go.mod中sigs.k8s.io/controller-runtime是否 ≥ v0.14.0（对应 K8s 1.25+）
Reconcile函数里无法获取Pod日志：client.Reader vs client.Client区别
很多新手在 Reconcile 函数里直接用 r.Client.Get() 取 Pod 然后想读日志，结果 panic —— 因为 client.Client 默认不缓存 Pod，而日志需要实时 API 调用，不是靠 List/Get 能拿到的。
-
r.Client是读写客户端，走 cache + API server 双路径；但 Pod 日志必须绕过 cache，走纯 REST 调用 - 正确做法是注入
rest.Interface或用corev1clientset.CoreV1().Pods(namespace).GetLogs(...)，注意该 client 需手动构造（从r.Client.Scheme()和config初始化） - 别在 Reconcile 中同步调用日志接口，它可能超时或阻塞队列；应转为 Event 或 Status 字段异步上报
CRD升级后旧对象无法解码：conversion webhook配置遗漏
加了新字段或改了类型后，老的 CR 实例在 kubectl get 时显示 error unmarshaling JSON，根本原因是没配 conversion webhook，Kubernetes 不知道如何把 v1alpha1 对象转成 v1 结构。
- 仅靠
kubebuilder create api --group xx --version v1 --kind YY不会自动生成 conversion 逻辑 - 必须手动在
config/crd/kustomization.yaml里取消注释patchesStrategicMerge并添加 conversion patch，再实现ConvertTo/ConvertFrom方法 - Webhook server 必须监听
/convert，且 TLS 证书需被 apiserver 信任（推荐用 kubebuilder 自动生成的 cert-manager 流程） - 本地调试时容易忽略：minikube 或 kind 集群默认不启用
CustomResourceWebhookConversionfeature gate，需显式开启
Operator部署后Reconcile不触发：OwnerReference和Finalizer陷阱
CR 创建后 Reconcile 一次就停住，后续更新或删除完全无响应，大概率是 OwnerReference 写错或 Finalizer 卡死。
立即学习“go语言免费学习笔记（深入）”；
- OwnerReference 的
uid必须严格匹配实际对象 UID（不是 name），用client.Get(ctx, key, &obj)后取obj.UID，别手写或复制粘贴 - 如果在 Reconcile 中创建了 Job 或 Deployment，又忘了给它们加
controllerutil.SetControllerReference()，Kubernetes 就不会自动触发级联 Reconcile - Finalizer 在删除流程中不移除，会导致 CR 卡在
Terminating状态，进而阻塞整个 namespace 的 GC；务必确保所有清理逻辑（如删除外部资源）完成后才调用ctrlutil.RemoveFinalizer()
CRD 的 schema 变更、webhook 的 TLS 配置、Finalizer 的清理时机——这三处一旦出问题，现象都像“Operator 失联”，但根因完全不同。查的时候别只盯 Reconcile 日志，先看 kubectl get crd -o wide 和 kubectl get mutatingwebhookconfigurations 是否就绪。
