标记语法

• Empty

+kubebuilder:validation:Optional：空标记像命令行中的布尔标记位-- 仅仅是指定他们来开启某些行为。

• Anonymous

+kubebuilder:validation:MaxItems=2：匿名标记使用单个值作为参数。

• Multioption

+kubebuilder:printcolumn:JSONPath=".status.replicas",name=Replicas,type=string：多选项标记使用一个或多个命名参数。第一个参数与名称之间用冒号隔开，而后面的参数使用逗号隔开。参数的顺序没有关系。有些参数是可选的。

标记的参数可以是字符，整数，布尔，切片，或者 map 类型。 字符，整数，和布尔都应该符合 Go 语法

// +kubebuilder:validation:ExclusiveMaximum=false
// +kubebuilder:validation:Format="date-time"
// +kubebuilder:validation:Maximum=42

为了方便，在简单的例子中字符的引号可以被忽略，尽管这种做法在任何时候都是不被鼓励使用的，即便是单个字符：

// +kubebuilder:validation:Type=string

切片可以用大括号和逗号分隔来指定。

// +kubebuilder:webhooks:Enum={"crackers, Gromit, we forgot the crackers!","not even wensleydale?"}

或者，在简单的例子中，用分号来隔开。

// +kubebuilder:validation:Enum=Wallace;Gromit;Chicken

Maps 是用字符类型的键和任意类型的值（有效地map[string]interface{}）来指定的。一个 map 是由大括号（{}）包围起来的，每一个键和每一个值是用冒号（:）隔开的，每一个键值对是由逗号隔开的。

// +kubebuilder:validation:Default={magic: {numero: 42, stringified: forty-two}}

CRD生成

放在最外层, 如printcolumn

修改完成后

make manifests

然后delete crd再apply crd

printcolumn

//+kubebuilder:object:root=true
//+kubebuilder:printcolumn:name="foo",type="string",JSONPath=".spec.foo",description="The Foo name"
//+kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"

• name: 展示的列的名称

• type: 展示的列的类型, 包括integer、number、string、boolean 和 date

• JSONPath: 在清单中的路径

• description: 描述

• priority : 当前列的优先级

效果如下:

$ kubectl get tenant 
NAME            FOO   AGE
tenant-sample   zoo   1s

resource

//+kubebuilder:resource:scope=Cluster,shortName=tnt

scope=Cluster:非命名空间资源, 若不加则为命名空间资源, 改成Cluster后需要先运行自定义控制器, 否则创建CR时会报错找不到CRD, 因为创建CR时如果不指定namespace, 默认会去default命名空间找

效果如下:

$ kubectl get tnt
NAME            FOO   AGE
tenant-sample   zoo   3s

status

开启status子资源, 即可使用r.Status().Update()更新状态

// +kubebuilder:subresource:status

skipversion

忽略该版本

//+kubebuilder:skipversion

storageversion

在多版本crd做转换的时候标记其为存储版本

//+kubebuilder:storageversion

scale

开启scale子资源

//+kubebuilder:subresource:scale:specpath=.spec.replicas,statuspath=.status.replicas

• selectorpath 指labelSelectorPathScale 对象的属性，该值jsonpath定义了对应的自定义资源内部的 JSONPath Scale.Status.Selector。这是个可选的选项。

• statuspath 指statusReplicasPathScale 对象的属性。并且jsonpath它的值定义了对应于Scale.Status.Replicas. 这是一个必填字段。

• specpath 指specReplicasPathScale 对象的属性，valuejsonpath定义了对应的自定义资源内部的 JSONPath Scale.Spec.Replicas。这是一个必填字段。

需要在spec中添加replicas字段

效果如下:

$ kubectl scale tnt tenant-sample --replicas=3
tenant.tenant.example.io/tenant-sample scaled

unservedversion

不提供此版本

//+kubebuilder:unservedversion

groupName

//+groupName=xx

覆盖此包的 API 组版本（默认为包名称）

versionName

//+versionName=xx

即

group name to use for REST API: /apis//

CRD验证

放在特定字段上方表示针对该字段, 或者结构体上方表示针对该结构体, 还可以放在包级别, 可以配合使用, 比如在包级别设置为true, 在字段级别设置为false从而达到单独给某个字段做限制的作用

default

默认值, 不在spec中定义则使用默认值

//+kubebuilder:default=defaultname
DefaultTest string `json:"defaultTest,omitempty"`

支持boolean: true, string: Cluster, numerical: 1.24, array: {1,2}, object: {policy: "delete"}

XEmbeddedResource

使用 apiVersion、Kind和metadata字段将字段标记为嵌入式资源。并与preserve-unknown-fields: true结合不会修剪该字段，并且该字段里面包含一个完整的对象。

默认情况下，定制资源的所有版本中的所有未规定的字段都会被剪裁掉。 通过在结构化的 OpenAPI v3 检查模式定义 中为特定字段的子树添加 x-kubernetes-preserve-unknown-fields: true 属性， 可以选择不对其执行剪裁操作。

// +kubebuilder:validation:XEmbeddedResource
// +kubebuilder:validation:XPreserveUnknownFields
type RawExtension struct {runtime.RawExtension `json:",inline"`
}type XXXSpec struct {//+kubebuilder:default=defaultnameDefaultTest string         `json:"defaultTest,omitempty"`RawItems    []RawExtension `json:"rawItems,omitempty"`
}

crd新增:

defaultTest:default: defaultnametype: string
rawItems:items:type: objectx-kubernetes-embedded-resource: truex-kubernetes-preserve-unknown-fields: truetype: array

cr使用:

defaultTest: "asdf"
rawItems:- apiVersion: v1kind: Secretmetadata:name: secret-1- apiVersion: v1kind: Secretmetadata:name: secret-2- apiVersion: v1kind: Secretmetadata:name: secret-3

EmbeddedResource

功能同XEmbeddedResource, 建议使用EmbeddedResource

// +kubebuilder:validation:EmbeddedResource
// +kubebuilder:validation:PreserveUnknownFields
type RawExtension struct {runtime.RawExtension `json:",inline"`
}type XXXSpec struct {//+kubebuilder:default=defaultnameDefaultTest string         `json:"defaultTest,omitempty"`RawItems    []RawExtension `json:"rawItems,omitempty"`
}

crd中如下

rawItems:items:type: objectx-kubernetes-preserve-unknown-fields: truetype: array

cr使用同XEmbeddedResource

Enum

枚举

// +kubebuilder:validation:Enum=Wallace;Gromit;Chicken
type Food stringtype xxxSpec struct {Food        Food           `json:"food"`
}

当填写一个其他数据时, 报错如下

The Tenant "tenant-sample" is invalid: spec.food: Unsupported value: "asdf": supported values: "Wallace", "Gromit", "Chicken"

Minimum / Maximum

最大值,最小值

// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=3
MaxMinTest int `json:"maxMinTest"`

ExclusiveMaximum / ExclusiveMinimum

最大值"达到"但不包括该值(最小值同) , 需要和Max和Min配合使用, 以下表示最大值为3, 但是ExclusiveMaximum限制了不包括3, 所以最大值为2

// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=3
// +kubebuilder:validation:ExclusiveMaximum=true
// +kubebuilder:validation:ExclusiveMinimum=false
ExclusiveMaximumTest int `json:"exclusiveMaximumTest"`

配置错误会报错

The Sample "sample" is invalid: spec.exclusiveMaximumTest: Invalid value: 3: spec.exclusiveMaximumTest in body should be less than 3

MaxItems / MinItems / UniqueItems

列表最大/最小数量, 是否唯一, 现已禁用UniqueItems, 因为会导致验证的复杂度变成2次方

https://groups.google.com/g/kubernetes-sig-api-machinery-proposals/c/Rn7QaNojCO4

也已说明UniqueItem不可设置为true

https://kubernetes.io/zh-cn/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation

// +kubebuilder:validation:MaxItems=3
// +kubebuilder:validation:MinItems=1
// +kubebuilder:validation:UniqueItems=false
ItemsTest []string `json:"itemsTest,omitempty"`

数量错误会报错

The Sample "sample" is invalid: spec.itemsTest: Too many: 3: must have at most 2 items

MaxLength / MinLength

字段value最大/最小长度

// +kubebuilder:validation:MaxLength=3
// +kubebuilder:validation:MinLength=1
LengthTest string `json:"lengthTest"`

MultipleOf

value必须是该值的倍数, 比如设置为3, 则value必须是6, 9等3的倍数

//+kubebuilder:validation:MultipleOf=3
MultipleOfTest int `json:"multipleOfTest,omitempty"`

错误配置报错如下

multipleOfTest: 10The Sample "sample" is invalid: spec.multipleOfTest: Invalid value: 10: spec.multipleOfTest in body should be a multiple of 3

Optional

表示该字段是可选的, 即使没有在结构体tag中加omitempty tag, 也可不在cr spec中定义

// +kubebuilder:validation:Optional
OptionalTest int `json:"optionalTest"`

也可省略如下, 相同的功能

// +optional
OptionalTest int `json:"optionalTest"`

Pattern

value值必须包含该值

// +kubebuilder:validation:Pattern="sample"
PatternTest string `json:"patternTest"`

比如

patternTest: "asdfsample"

Required

表示该字段为i必须的, 但是omitempty优先级更高, 只要配置了omitempty, 即变为非必须, 而不配omitempty就是必须

// +kubebuilder:validation:Required
RequiredTest int `json:"requiredTest,omitempty"`

Type

覆盖该字段的类型（默认为 Go 类型的等价物）, 这通常必须与自定义序列化配对, 例如，metav1.Time 字段将被标记为"type: string"和"format: date-time"

Nullable

允许该value为空, 不像只配置为omitempty, 如果value为空, yaml结果中不会展示该字段

// +nullable
NullTest int `json:"nullTest"`

cr配置

nullTest:

yaml结果

nullTest: null

CRD处理

PreserveUnknownFields

使用方式及说明见 CRD验证 EmbeddedResource

// +kubebuilder:pruning:PreserveUnknownFields

XPreserveUnknownFields

使用方式及说明见 CRD验证 XEmbeddedResource, 已被PreserveUnknownFields取代

https://github.com/kubernetes-sigs/controller-tools/pull/422

WebHook

• failurePolicy : 指定如果 API 服务器无法访问 webhook 时的策略, 可选参数为 fail 和 ignore

• groups <[]string>: 指定此 webhook 接收请求的 API 组

• matchPolicy : 定义"规则"列表用于如何匹配传入请求, 允许的值为"Exact"（仅当它与指定规则完全匹配时才匹配）或"Equivalent"（如果请求修改了规则中列出的资源，则匹配请求，即使是通过另一个 API 组或版本）

• mutating : 启用mutating webhook

• name : 此webhook的名称

• path : 指定 API 服务器应连接到此 webhook 的路径。 必须以 '/validate-' 或 '/mutate-' 为前缀，具体取决于类型，然后是 $GROUP-$VERSION-$KIND，其中所有值都是小写的，组中的句点用连字符代替。 例如，类型 batch.tutorial.kubebuilder.io/v1,Kind=CronJob 的验证 webhook 路径为 /validate-batch-tutorial-kubebuilder-io-v1-cronjob

• resources <[]string>: 设置监控的api资源 例如:deployments

• sideEffects : 指定调用 webhook 是否会有副作用。 这对dry run和 `kubectl diff` 有影响：如果 sideEffect 是"Unknown"（默认）或"Some"，那么 API 服务器将不会在空运行请求上调用 webhook，而是失败。 如果值为"None"，则 webhook 没有副作用，API 服务器将在试运行时调用它。 如果该值为"NoneOnDryRun"，则 Webhook 负责检查请求中发送的 AdmissionReview 的"dryRun"属性，dryRun被设置为"true"时没有副作用

• verbs <[]string>: 指定此 webhook 接收请求的 Kubernetes API 动作。可以是"create"、"update"、"delete"、"connect"或"*"（适用于所有)

• versions <[]string>: 指定此 webhook 接收请求的 API 版本

• admissionReviewVersions <[]string>: 可接受的 AdmissionReview 对象版本 , 比如"v1", "v1beta1"

示例

//+kubebuilder:webhook:path=/validate-sample-example-io-v1-sample,mutating=false,sideEffects=None,admissionReviewVersions=v1,failurePolicy=fail,groups="*",resources="*",verbs=create;update;delete,versions="*",name=sample.validate.example.io

Object/DeepCopy

generate

启用或禁用此类对象的深拷贝生成, true / false

可作用于结构体或者整个包, 比如可以在整个包作用域下设置为true(可在groupversion_info.go中设置), 但对特定的结构体设置为false

// +kubebuilder:object:generate=true

root

为该类型生成object接口

//+kubebuilder:object:root=true

RBAC

• groups <[]string>: 指定api 组, 比如 deployment 属于apps组

• namespace: 如果指定了命名空间, 则作用在该命名空间, 否则作用在全局

• resourceNames <[]string>: 包含的 API 资源的名称, 比如abc-deployment

• resources <[]string>: 包含的资源类型, 比如deployments

• urls <[]string>: 访问非资源的URL

• verbs <[]string>: 对资源的操作，比如get;list;watch;create;update;patch

// +kubebuilder:rbac:groups=sample.example.io,resources=samples,verbs=get;list;watch;create;update;patch;delete