Kubebuilder 通过 kubebuilder init 和 kubebuilder create api 两条命令即可生成可运行的 Operator 骨架，自动完成 CRD YAML、Scheme 注册、Manager 初始化及 Reconcile 框架等样板代码；但需严格满足 Go ≥1.24.6、kubectl ≥1.11.3、docker ≥17.03 环境要求，且 PROJECT 文件配置、注释驱动的 CRD 生成（如 // +kubebuilder:object:root=true）和 make install 与 make run 的执行顺序均不可出错。
直接用 kubebuilder init 和 kubebuilder create api 两条命令就能生成可运行的 Operator 骨架，不需要手写 CRD YAML、Scheme 注册、Manager 初始化或 Reconcile 循环框架。
初始化项目前必须确认 Go 和 kubectl 版本
不是所有组合都能跑通。Kubebuilder v4（当前主流）明确要求：
-
go≥ v1.24.6：低于此版本会因泛型或 embed 支持不足导致make generate失败 -
kubectl≥ v1.11.3：用于make install应用 CRD，旧版不识别 v1 CRD 的某些字段 -
docker≥ 17.03：make docker-build依赖它构建 manager 镜像
漏掉任一条件，后续 make manifests 可能静默失败，或 make run 报错 “no matches for kind”——这不是代码问题，是环境没对齐。
kubebuilder init 后 PROJECT 文件决定行为边界
执行 kubebuilder init --domain example.com --repo example.com/myop 后，根目录生成的 PROJECT 是关键配置文件，它控制后续所有命令的行为：
立即学习“go语言免费学习笔记（深入）”；
评估 Kubernetes 集群安全态势，覆盖 RBAC、工作负载安全、网络策略、基础设施即代码（IaC）、运行时监控和密钥管理等 30 项控制项……
-
layout: ["go.kubebuilder.io/v4"]表示使用 v4 脚手架，启用kustomize/v2插件，make deploy会走 kustomize 流程 -
resources:下为空时，kubebuilder create api才允许添加新资源；若已有条目，需先删再加，否则报错 “resource already exists” - 修改
domain或repo后，必须手动更新go.mod和所有import路径，否则make build找不到包
这个文件不是只读文档，它是 Kubebuilder 运行时的“配置源”，改完要重新跑 make generate 和 make manifests。
make manifests 生成 CRD 的本质是解析 //+kubebuilder 注释
CRD 不是从结构体自动推导的，而是靠你在 api/.../xxx_types.go 里写的标记注释驱动生成：
-
// +kubebuilder:object:root=true标记 struct 是顶层资源（如CronJob） -
// +kubebuilder:subresource:status启用 status 子资源，否则UpdateStatus()会 404 - 字段级注释如
// +kubebuilder:validation:Required会转成 CRD 的required字段，漏写会导致kubectl apply时校验失败 - 改完注释必须运行
make manifests，否则config/crd/bases/下的 YAML 不更新，集群里还是旧 Schema
常见错误是手动编辑 config/crd/bases/... 下的 YAML——下次 make manifests 会直接覆盖，所有改动丢失。
make run 本地调试时 Controller 不生效的三个硬坑
make run 启动的是本地进程，不依赖集群中的 manager Deployment，但容易卡在以下环节：
- RBAC 没装：
make install必须先执行，否则 controller 报 “forbidden: user system:serviceaccount:default:default cannot get resource” - CRD 没装：
make install包含 CRD 安装，但如果你删过config/crd目录又没重跑，make install会静默跳过 - Reconcile 逻辑里用了
client.Get()查非 namespaced 资源（如Node），但默认 RBAC 没授权——需要手动在config/rbac/role.yaml里加 rules
本地调试最稳的链路是：make install → kubectl apply -f config/samples/ → make run，缺一不可。任何一步跳过，都会让 Reconcile 看不到事件或拿不到对象。
