crd yaml 必须严格符合 v1 schema 规范，否则 controller-gen 生成的 go 类型缺字段、无 deepcopy、无法注册 scheme，导致 client 操作 panic；需显式声明 type、additionalproperties、大小写及命名格式，并确保 yaml 与 go 注释、scheme 注册完全一致。
CRD YAML 写对了，controller-gen 才能生成可用的 Go 类型；否则生成的 struct 缺字段、没 DeepCopy、无法注册进 Scheme，后续 client 操作直接 panic。
CRD YAML 必须满足 v1 版本的 schema 约束
从 apiextensions.k8s.io/v1beta1 升级到 v1 后，schema 校验变严格：必须显式声明 additionalProperties: false（若不希望允许额外字段），且所有嵌套 properties 都要带 type。常见错误是漏写 spec 或 status 的 type: object，导致 controller-gen 生成的 Go struct 中对应字段为 interface{}，无法做类型安全操作。
-
openAPIV3Schema下第一层必须是type: object，且properties中每个子字段都需明确定义type - 若字段可选，用
// +optional注释（Go 侧）或"nullable": true（YAML 侧），二者要一致 -
scope: Namespaced和scope: Cluster决定生成的 Go struct 是否嵌入metav1.ObjectMeta还是metav1.ClusterObjectMeta
用 controller-gen 生成 Go 类型前先校验 CRD
别跳过 kubectl apply --dry-run=client -o wide -f crd.yaml。很多生成失败的根源其实是 YAML 本身语法或语义错误，比如 versions[0].name 和 names.kind 大小写不一致，或 plural 不是全小写复数形式（如写成 Database 而非 databases），controller-gen 不会报这类错，但生成的 clientset 在调用 List() 时会因 URL 路径拼错而 404。
- 确保
metadata.name格式为<plural>.<group></group></plural>（如databases.example.com），这是 API endpoint 的路由依据 - 运行
controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."前，先确认目录下有带// +kubebuilder:object:root=true的 Go 文件作为入口 - 生成后检查
types.go中的 struct 是否含DeepCopyObject()方法——没有说明注释没生效或路径没扫到
生成的 Go 类型必须注册到 Scheme 才能被 client-go 使用
哪怕 controller-gen 成功输出了 MyApp 结构体，如果没把它加进 scheme.Scheme，client.Get() 或 client.Create() 就会报 no kind "MyApp" is registered for version "example.com/v1"。这不是代码逻辑错，是 Scheme 初始化漏步骤。
- 在
main.go或scheme/addtoscheme_example_v1.go中调用examplev1.AddToScheme(scheme) - 确保导入的 scheme 包和 CRD 的
group/version完全匹配（大小写、斜杠、点号都不能差） - 若用 Kubebuilder，
api/v1/zz_generated.deepcopy.go必须存在且被 go build 看见；缺失会导致 runtime panic
真正卡住人的从来不是“怎么写 CRD”，而是 YAML 里一个冒号缩进错位，或 Go 注释少了个加号，就让整个类型链断裂。生成代码只是中间环节，关键在两端对齐：YAML 描述的结构，和 Scheme 认出的类型，必须字节级一致。
