如何配置Golang Kubernetes Operator CRD-Golang-PHP中文网

CRD YAML 中关键字段不可错：apiVersion 必须为 apiextensions.k8s.io/v1；spec.group、spec.names.kind、spec.names.plural、spec.scope 必须严格匹配且大小写敏感；OpenAPI v3 schema 中 spec/status 需显式声明 type: object，字段类型须准确（如 integer/string/boolean），数组须含 items；结构体需 +kubebuilder:validation 注解才能生成 schema；storage 版本有且仅有一个，须 served: true 且 storage: true。

如何配置golang kubernetes operator crd

CRD YAML 文件里哪些字段不能错

CRD 的 apiVersion 必须是 apiextensions.k8s.io/v1（K8s v1.16+ 强制要求），v1beta1 已废弃且在 v1.22+ 完全不可用。常见错误是复制旧文档里的 v1beta1，导致 kubectl apply 报错 no matches for kind "CustomResourceDefinition"。

关键字段必须成对匹配：

spec.group（如 cache.example.com）要和 Go 类型注册时的 GroupVersion.Group 一致
spec.names.kind（如 RedisCluster）需首字母大写，且必须与 Go struct 名、register.go 中的 Kind 字段完全一致
spec.names.plural（如 redisclusters）决定 kubectl get 命令路径，拼写错误会导致资源无法列出
spec.scope 只能是 Namespaced 或 Cluster，大小写敏感；写成 namespaced 会静默降级为 Cluster 级但不报错，极易引发权限和隔离问题

OpenAPI v3 schema 怎么写才不被 API Server 拒绝

CRD 的 schema 不是可选装饰，而是强制校验入口。漏掉 type: object 或嵌套 properties 缺失顶层 spec 定义，会导致 kubectl apply 成功但后续 kubectl create -f cr.yaml 直接返回 Invalid value: : spec is required。

实际写法要点：

spec 和 status 必须显式声明为 type: object，即使为空也要写 properties: {}
所有字段类型必须明确：整数用 type: integer（不是 int 或 number），字符串用 type: string，布尔用 type: boolean
可选字段加 "x-kubernetes-preserve-unknown-fields": true 是危险操作——它绕过校验，但会让 controller-runtime 的 Go 结构体反序列化失败，出现 json: unknown field "xxx"
数组字段必须带 items，例如 type: array; items: { type: string }，光写 type: array 会触发校验失败

为什么 kubebuilder generate 后 CRD YAML 里没生成 schema

这是最常被忽略的标记问题：api/v1/xxx_types.go 中的结构体字段**必须有 +kubebuilder:validation 注解才能进 schema**。没有注解的字段，controller-gen 默认跳过，生成的 CRD YAML 中对应字段直接消失。

正确示例：

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

type MyAppSpec struct {
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=100
    Replicas int `json:"replicas"`
    
    // +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
    Image string `json:"image"`
}

漏掉注解的后果：

Replicas 字段在 CRD YAML 的 openAPIV3Schema 中彻底缺失 → 创建 CR 时该字段不被校验，但 Go struct 反序列化会设为零值（如 int=0）
Image 缺少 Pattern → 用户填 nginx:latest 能过，填 NGINX:LATEST 也能过，失去约束意义
整个 MyAppSpec 结构体若没加 // +kubebuilder:object:root=true，controller-gen 甚至不会把它当 CR 类型处理

storage 版本和 served 版本怎么配才不出问题

一个 CRD 可以定义多个版本（如 v1alpha1, v1），但有且仅有一个版本能同时满足 served: true 和 storage: true。违反这点，kubectl get crd 会显示 ESTABLISHED=False，且所有 CR 操作失败。

典型配置组合：

新项目起步：只留一个 v1，设 served: true 和 storage: true，其他版本删掉
升级场景：新增 v1（served: true, storage: false），原 v1alpha1 改为 served: true, storage: false，再部署 conversion webhook
绝对禁止：v1alpha1 和 v1 都设 storage: true —— API Server 会拒绝创建 CRD，报错 only one version can be marked as the storage version
注意：served: false 的版本仍可读（如果已有对象存于该版本），但无法通过 kubectl apply 创建新对象