operator-sdk init 报错 failed to generate rbac rules，主因是 go.mod 模块路径含大写字母、特殊符号或数字开头，需改用全小写、中划线分隔格式（如 example.com/redis-operator），并确保不在 $gopath/src 下；v1.30+ 还需 controller-gen 与 kubectl 版本匹配。
operator-sdk init 为什么报错 failed to generate RBAC rules
初始化项目时卡在 RBAC 生成，常见原因是 go.mod 里模块路径含大写字母、特殊符号或以数字开头——Kubernetes 的 RBAC 规则名会直接映射为 DNS 子域名格式，operator-sdk 内部校验不通过。
- 检查
go mod init指定的模块名，改用全小写、中划线分隔的格式，例如go mod init example.com/redis-operator - 确保当前目录不在
$GOPATH/src下（SDK v1.0+ 已弃用 GOPATH 模式，混用会触发奇怪的路径解析错误） - 如果用的是 SDK v1.30+，还需确认
kubectl和controller-gen版本匹配：运行controller-gen --version，输出应与go get sigs.k8s.io/controller-tools/cmd/controller-gen@v0.14.0中的版本一致
Reconcile 函数里 return nil 还是 requeue
Reconcile 返回 ctrl.Result{} 和 error 是两个独立信号：前者控制是否重入队列，后者决定是否记录事件并中断本次处理。新手常误以为 “没错误就不用重试”，结果状态同步延迟甚至卡死。
- 需要等待外部条件就绪（如 Pod 启动、ConfigMap 被挂载），返回
ctrl.Result{RequeueAfter: 5 * time.Second}，避免空转轮询 - 发现资源缺失（如 Secret 不存在），应返回
err（非 nil），让 controller runtime 记录 Warning 事件，并按指数退避重试 - 修改了对象但未调用
Update()或Patch()，仅 return nil → 状态不会持久化，下次 Reconcile 仍看到旧值
如何让 Operator 只管理特定 namespace 而不是集群全局
默认 operator-sdk init 生成的是 ClusterScope Operator，RBAC 和控制器启动参数都面向整个集群。若只需管单个命名空间，改动点集中在三处，漏掉任一都会导致权限拒绝或监听失效。
- 修改
main.go中mgr, err := ctrl.NewManager的cache.DefaultCacheOptions，显式设置Namespaces: map[string]cache.Config{"my-ns": {}} - 删掉
config/rbac/role.yaml里的ClusterRole和ClusterRoleBinding，保留Role和RoleBinding，并把subjects.namespace改成目标 ns - 部署时用
kubectl apply -n my-ns -f config/default/，且确保config/manager/manager.yaml中容器启动参数不含--leader-elect=false（单 namespace 场景下 leader election 仍需启用）
更新 CRD 后 kubectl apply 报错 invalid value: "v1alpha1"
CRD 升级时，如果新增了 versions 字段但没设 storage: true，或者旧版本被标记为 served: false 但仍有存量对象，kubectl apply 就会拒收，提示版本无效。
立即学习“go语言免费学习笔记（深入）”；
- CRD 的
versions列表中，有且仅有一个版本可设storage: true；其他版本只能served: true用于读，不能存数据 - 升级前先用
kubectl get <crd-name>.example.com -o yaml</crd-name>查看当前 storage 版本，再决定新版本是否兼容（比如 v1alpha1 → v1beta1，需写 migration logic） - 如果只是改字段标签（如加
x-kubernetes-int-or-string: true），不要动versions结构，否则 API server 会拒绝变更
CRD 版本管理和对象存储策略是 Operator 上线后最难调试的部分，尤其当多个环境共用一套 CRD 定义时，storage 版本错位会导致整个 CR 类型不可用，比代码逻辑错误更难定位。
