CRD YAML 必须用 spec.versions 数组（非弃用的 spec.version），每个版本含 name、served、storage 字段，且仅一个设 storage: true；OpenAPI v3 类型需严格书写（如 integer 非 int）；controller-runtime 中需显式 AddToScheme 并确保类型与 CRD group/kind 完全匹配；OwnerReference 应用 meta.IsControlledBy 校验；Webhook 的 caBundle 必须正确注入 ValidatingWebhookConfiguration。
CRD YAML 怎么写才不会被 kubectl apply 拒绝
CRD 的 spec.version 字段已弃用，K8s 1.16+ 必须用 spec.versions（数组），且至少一个版本需设 storage: true。常见错误是直接复制旧文档里的单版本写法，导致报错：error: error validating "crd.yaml": [ValidationError(CustomResourceDefinition.spec): unknown field "version" in io.k8s.apiextensions-apiserver.pkg.apis.apiextensions.v1.CustomResourceDefinitionSpec]。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
spec.versions数组中，每个元素必须包含name、served和storage字段；仅一个版本可设storage: true - 推荐把最新版（如
v1）设为storage: true，旧版（如v1alpha1）设served: true但storage: false，方便后续迁移 - 字段类型定义必须严格使用 OpenAPI v3 格式，比如
int要写成integer，bool写成boolean，否则kubectl apply会静默忽略 validation 规则 - 避免在
spec.validation.openAPIV3Schema.properties下直接写type: object—— K8s 要求显式声明properties或additionalProperties
controller-runtime 的 Builder 怎么绑定 CRD 类型
Controller 启动时找不到自定义资源，通常不是 CRD 没装，而是 Builder 没正确注册 Scheme。controller-runtime 默认只认识内置资源（corev1.Pod 等），你的 MyApp 类型必须显式添加到 Scheme 中，否则 mgr.GetClient() 查询会返回 no kind "MyApp" is registered for version "example.com/v1"。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在
main.go初始化 manager 前，调用appsv1.AddToScheme(scheme)（其中appsv1是你生成的 client-go 包路径），不是appsv1.SchemeBuilder.AddToScheme - 确保
Builder.For(&appsv1.MyApp{})中的类型指针与 CRD 的spec.group/spec.names.kind完全匹配（大小写、复数形式都敏感） - 如果用了多版本 CRD，所有版本类型（如
MyAppV1Alpha1、MyAppV1）都要分别AddToScheme，否则 watch 旧版本对象会失败 - 不要在
SetupWithManager里重复调用AddToScheme—— Scheme 是全局单例，重复注册会 panic
Reconcile 函数里怎么安全读取 OwnerReference
想让 Controller 自动处理级联删除，但直接访问 obj.GetOwnerReferences() 取出来的 OwnerReference 里 UID 是空字符串，或者 Kind 大小写不一致，导致 client.List() 查不到父资源 —— 这是因为 OwnerReference 是由 K8s 自动注入的，但只在对象被创建时写入，且不校验字段合法性。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 优先用
client.ObjectKey{Namespace: obj.GetNamespace(), Name: owner.Name}构造 key，而不是依赖owner.UID去查 —— UID 在跨集群或备份恢复场景下不稳定 - 检查
owner.Kind是否等于你的期望值（如"MyApp"），注意它来自 YAML 的kind字段，不是 Go struct 名，所以大小写必须完全一致 - 用
meta.IsControlledBy(obj, parent)替代手写比对逻辑，这个函数会同时校验APIVersion、Kind、Name和UID，更健壮 - 如果 Owner 对象已被删，
client.Get()会返回errors.IsNotFound(err)，别直接 panic，应记录日志后 return nil 让 reconcile 结束
Webhook Server 启动失败：x509 certificate signed by unknown authority
启用 ValidatingWebhookConfiguration 后，Controller 日志出现 x509: certificate signed by unknown authority，本质是 apiserver 调用你的 webhook 时，不信任你提供的 TLS 证书 —— 它只认 CA bundle，而这个 bundle 必须通过 caBundle 字段注入到 ValidatingWebhookConfiguration 中，不是靠证书链自动传递。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 别用自签名证书直接丢给 webhook server；先用
cfssl或openssl生成一对 CA + server cert，然后把 CA 的 PEM 内容（base64 编码后）填进webhookConfiguration.webhooks[0].clientConfig.caBundle - 证书的
Subject.CommonName或DNSNames必须包含 service DNS 名，典型格式是myapp-webhook.myapp-system.svc，不能只写myapp-webhook - controller-runtime 的
builder.Complete()不会自动注入 caBundle，得自己用脚本或 kustomize 在部署前替换 —— 常见做法是先生成证书，再用sed或kustomize cfg set注入 - 本地调试时可用
--cert-dir启动 webhook，但生产环境必须用正式证书，因为 K8s apiserver 不接受insecureSkipTLSVerify: true
CA bundle 错一位、service name 少一个 .svc、证书过期、没重启 webhook pod —— 这些细节只要漏一个，整个 admission 链就断了，而且错误日志藏在 apiserver 里，不容易定位。
