CRD通过YAML注册到API Server,Go中仅定义带kubebuilder注释的结构体,由controller-gen自动生成v1版CRD YAML;需验证ESTABLISHED状态及kubectl explain字段生效。

CRD 不是用 Go “定义”出来的,而是通过 YAML 文件注册到 Kubernetes API Server 的。Go 代码里写的只是对应 CRD 的**结构体映射**和**生成逻辑**——它服务于 controller-gen 工具自动生成真正的 CRD YAML。
你真正要做的,是用 Go 类型 + 特殊注释(markers)告诉 controller-gen:这个结构体该生成什么样的 CustomResourceDefinition。
怎么写 Go 结构体并让它生成合法的 CRD YAML
核心不是手写 YAML,而是写带标记(marker)的 Go 类型,再让工具生成。
-
// +kubebuilder:object:root=true标记该结构体为 CR 的顶层对象(即对应kind) -
// +kubebuilder:subresource:status表示启用status子资源(否则r.Status().Update()会失败) -
// +kubebuilder:printcolumn:可配置kubectl get默认输出列(比如加AGE或STATUS) - 字段上用
json:"fieldName"控制序列化名,这直接变成 CRD schema 中的字段名 -
Spec和Status必须是嵌套结构体,不能是 map 或 interface{}
例如,一个最小可用的 RedisCluster 类型:
package v1
import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
//+kubebuilder:object:root=true
//+kubebuilder:subresource:status
//+kubebuilder:printcolumn:name="Replicas",type="integer",JSONPath=".spec.replicas"
//+kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
type RedisCluster struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec RedisClusterSpec `json:"spec,omitempty"`
Status RedisClusterStatus `json:"status,omitempty"`
}
type RedisClusterSpec struct {
Replicas int32 `json:"replicas"`
Image string `json:"image"`
}
type RedisClusterStatus struct {
ObservedGeneration int64 `json:"observedGeneration,omitempty"`
ReadyReplicas int32 `json:"readyReplicas,omitempty"`
Conditions []Condition `json:"conditions,omitempty"`
}
//+kubebuilder:object:root=true
type RedisClusterList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Items []RedisCluster `json:"items"`
}
为什么 make manifests 生成的 CRD YAML 总是 v1 而不是 v1beta1
Kubernetes v1.22+ 已废弃 apiextensions.k8s.io/v1beta1,controller-gen(v0.11+)默认只输出 v1 版本 CRD。如果你在集群中看到 error: unable to recognize "xxx.yaml": no matches for kind "CustomResourceDefinition" in version "apiextensions.k8s.io/v1beta1",说明你用的是旧版工具或手动写了 v1beta1 YAML。
- 确认
controller-gen --version≥ v0.11.0 - 检查
Makefile中manifests:目标是否调用controller-gen crd:crdVersions=v1(新版默认就是 v1,显式写更稳妥) - 不要手动改生成的 YAML 里的
apiVersion—— 下次make manifests会被覆盖
生成后怎么验证 CRD 是否符合预期
生成只是第一步,真正落地前必须校验三件事:
-
kubectl apply -f config/crd/bases/xxx.yaml成功不报错(注意:CRD 是集群级资源,命名空间参数无效) -
kubectl get crd redisclusters.cache.example.com显示ESTABLISHED状态(非PENDING),且AGE有值 -
kubectl explain rediscluster.spec.replicas能打印出字段说明 —— 这证明 OpenAPI schema 生效了;如果提示error: field "replicas" does not exist,大概率是没加json:"replicas"tag 或 marker 没生效
最常被忽略的一点:controller-gen 不读取 go build 结果,它只扫描源码文件里的 marker 注释。删掉注释、拼错 marker 名字(比如写成 +kubebuiler)、或者把注释放在结构体声明之后——都会导致字段不出现在生成的 CRD schema 里,但编译和运行时完全不报错。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











