Operator SDK 开发需对齐底层机制：kubebuilder 版本、RBAC 权限、conversion webhook、事件注册与 client 语义缺一不可，任一环节错配均导致初始化失败、Reconcile 不触发或对象解码异常。
Operator SDK 是目前最主流的 Go 语言 Operator 开发入口，但它不是“装完就能跑”的黑盒工具——初始化失败、Reconcile 不触发、CRD 升级后旧对象解码失败，这些都不是配置漏了那么简单，而是底层机制没对齐。
operator-sdk init 报错“kubebuilder not found”或卡住
这不是 operator-sdk 自己的问题，而是它默认调用 kubebuilder 二进制生成 scaffold。v1.30+ 版本要求 kubebuilder v3.20+，但 Homebrew/macOS 默认装的是 v4，Windows PowerShell 改了 PATH 也不生效。
- 先运行
kubebuilder version，没输出就去 GitHub releases 下对应平台的kubebuilder_3.20.0二进制，解压后加到 PATH - macOS 用 Homebrew：必须
brew install kubebuilder@3，别用brew install kubebuilder - Windows 用户改完
$env:PATH后要重启终端，PowerShell 不自动 reload 环境变量 - 确认
GO111MODULE=on，否则go mod tidy会失败；go version必须 ≥ 1.19（v2+ 插件强制要求）
Reconcile 函数里 client.Get 拿不到 CR 或 Pod 日志
现象是 r.Client.Get(ctx, req.NamespacedName, &myCR) 返回 NotFound，或者想读 Pod 日志却 panic —— 这两类问题根源完全不同。
- CR 拿不到：大概率是 RBAC 权限缺失或 scope 错配。检查
config/rbac/role.yaml是否包含对你 CRD 的get/list/watch权限，资源名必须和 CRD 文件中spec.names.plural完全一致（比如redisclusters，不是RedisCluster） - 如果是 ClusterScoped CRD，但用了
req.NamespacedName，就会去 namespace 下找，应改用types.NamespacedName{Name: req.Name} - Pod 日志不能用
r.Client.Get()拿：client.Client 默认走 cache，而日志是实时 REST 调用。必须用corev1clientset.CoreV1().Pods(namespace).GetLogs()，且该 client 需从rest.InClusterConfig()和r.Scheme手动构造 - 别在 Reconcile 中同步调用日志接口，超时会阻塞整个 reconcile queue；应转为异步上报到 CR status 或 Event
CRD 升级后老对象 error unmarshaling JSON
加了个字段、改了类型、甚至只是把 string 改成 *string，kubectl get 就报错，说明 Kubernetes 不知道怎么把旧版本对象转成新结构 —— conversion webhook 是强制项，不是可选。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
-
kubebuilder create api不会自动生成 conversion 逻辑，必须手动在config/crd/kustomization.yaml中取消注释patchesStrategicMerge并添加 conversion patch - 实现
ConvertTo/ConvertFrom方法时，注意字段映射顺序和零值处理，尤其是指针与非指针混用场景 - Webhook server 必须监听
/convert路径，TLS 证书需被 kube-apiserver 信任；本地调试建议用make cert-manager+cert-manager自动签发，别手动生成 - 升级前先确保所有旧对象已通过
kubectl convert或 controller 一次性迁移完成，否则 apiserver 会拒绝服务
Reconcile 不触发，Manager 启动成功但没反应
日志显示 Starting manager，但你改了 CR、删了 Deployment，reconcile 函数完全不执行 —— 这说明事件根本没推到你的 Controller。
- 检查
SetupWithManager里是否调用了.Owns(&appsv1.Deployment{})；漏掉这句，Deployment 变更就不会触发 Reconcile - 如果依赖 ConfigMap 或 Secret，别用
GenerationChangedPredicate{}：它们更新不会改metadata.generation，得用func(e event.UpdateEvent) bool { return !reflect.DeepEqual(e.ObjectOld, e.ObjectNew) } - 确保 CRD 已
kubectl apply -f config/crd/bases/...成功部署，且kubectl get crd显示ACCEPTED状态；否则 controller-runtime 初始化时会静默跳过该类型 - 用
kubectl auth can-i list redisclusters --all-namespaces验证 RBAC 是否真正生效，权限不足时也表现为静默无响应
Operator 开发里最易被忽略的点，是把 “写个函数处理 CR” 当成终点。实际上，CRD 注册时机、Scheme 类型注册顺序、OwnerReference 构造方式、conversion webhook 的 TLS 信任链、甚至 client.Get 的命名空间语义 —— 全部是强耦合的链条，断一环，整个控制循环就停摆。调试时别只盯 Reconcile 函数，先确认事件能不能进来、对象能不能解出来、子资源能不能归属上。
