kubebuilder-标记注释
导读KubeBuilder 使用称为controller-gen生成实用程序代码和 Kubernetes 对象 YAML 的工具,例如 CustomResourceDefinitions。为此,它使用特殊的“标记注释”(以 开头的注释// +)来指示有关字段、类型和包的附加信息。kubebuilder的标记注释官网讲解那么接下来让我们开始走进 “标记注释”CRD生成关于CRD生成时的可以进行的配置
导读
KubeBuilder 使用称为controller-gen
生成实用程序代码和 Kubernetes 对象 YAML 的工具,例如 CustomResourceDefinitions。
为此,它使用特殊的“标记注释”(以 开头的注释// +
)来指示有关字段、类型和包的附加信息。
那么接下来让我们开始走进 “标记注释”
CRD生成
关于CRD生成时的可以进行的配置,就有10多种,下面让我们一一分析
例子:
//+kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
type Toy struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec ToySpec `json:"spec,omitempty"`
Status ToyStatus `json:"status,omitempty"`
}
+kubebuilder:printcolumn
kubectl 工具依赖于服务器端的输出格式。您的集群的 API 服务器决定该命令显示哪些列kubectl get
。
// +kubebuilder:printcolumn:JSONPath=<string>,description=<string>,format=<string>,name=<string>,priority=<int>,type=<string>
- +kubebuilder:printcolumn 为此 CRD 向“kubectl get”输出添加一列,就是我们在调用kubectl get时多输出一个列我们自定义的列
- JSONPath 指明要输出的变量在CRD类中的位置,JSONPath=
.spec.alias
就是表示,输出值是spec中的alias变量。 - description 对该列进行的描述
- format 打印是的格式
- name 列的名字
- priority 显示该列的重要性,比如如果终端宽度不足以显示所有的列,那么就会根据该值进行过滤
- 具有优先级
0
的列显示在标准视图中。 - 优先级大于
0
的列仅在宽视图中显示。
- 具有优先级
- type 列中值的类型 如果 CustomResource 中的值与为列指定的类型不匹配,则忽略该值。使用 CustomResource 验证来确保值类型正确。
+kubebuilder:resource
+kubebuilder:resource:categories=<string>,path=<string>,scope=<string>,shortName=<string>,singular=<string>
-
+kubebuilder:resource 配置CRD的一些资源信息
-
categories 指定CRD 所属的组 一般是all,这样就可以使用kubecil get all 进行获取
-
path kind的复数形式
-
scope 指定crd资源作用范围在命名空间或集群 默认是命名空间 如果是基于namespace的。则API格式为:/apis/{group}/v1/namespaces/{namespace}/{spec.names.plural}/… 如果是基于cluster的。则API格式为:/apis/{group}/v1/{spec.names.plural}/…
-
shortName CRD资源别名
-
singular 在CLI(shell界面输入的参数)上用作别名并用于显示的单数名称
比如$ kubectl get pod pod1
$ kubectl get pods pod1
$ kubectl get po pod1 是等价的
+kubebuilder:skipversion
从 CRD 规范中删除特定版本的 CRD
+kubebuilder:storageversion
将此版本标记为 CRD 的“存储版本”以进行转换
+kubebuilder:subresource:scale
//+kubebuilder:subresource:scale:selectorpath=<string>,specpath=<string>,statuspath=<string>
在 CRD 上启用“/scale”子资源
-
selectorpath 指
labelSelectorPath
Scale 对象的属性,该值jsonpath
定义了对应的自定义资源内部的 JSONPathScale.Status.Selector
。这是个可选的选项。 -
statuspath 指
statusReplicasPath
Scale 对象的属性。并且jsonpath
它的值定义了对应于Scale.Status.Replicas
. 这是一个必填字段。 -
specpath 指
specReplicasPath
Scale 对象的属性,valuejsonpath
定义了对应的自定义资源内部的 JSONPathScale.Spec.Replicas
。这是一个必填字段。例子:
//+kubebuilder:subresource:scale:specpath=.spec.replicas,statuspath=.status.replicas,selectorpath=.status.selector
+kubebuilder:subresource:status
在 CRD 上启用“/status”子资源
+kubebuilder:unservedversion
不提供此版本
+kubebuilder:skip
不要将此包视为 API 版本。
+versionName:=
覆盖此包的 API 组版本(默认为包名称)
+ groupName:=
group name to use for REST API: /apis/<group>/<version>
指定REST API 的group
对于CRD生成时对于资源等一系列操作的标记注释已经分析完毕,接下来开始进行CRD validation工作
CRD validation
例子:
type ToySpec struct {
// +kubebuilder:validation:MaxLength=15
// +kubebuilder:validation:MinLength=1
Name string `json:"name,omitempty"`
// +kubebuilder:validation:MaxItems=500
// +kubebuilder:validation:MinItems=1
// +kubebuilder:validation:UniqueItems=true
Knights []string `json:"knights,omitempty"`
Alias Alias `json:"alias,omitempty"`
Rank Rank `json:"rank"`
}
使用方法: 在需要验证的元素上添加注释
+kubebuilder:default=
设置字段的默认值 。常见类型的格式包括:boolean: true
, string: Cluster
, numeric: 1.24
, array: {1,2}
, object: {policy: "delete"}
)。
+kubebuilder:validation:EmbeddedResource
EmbeddedResource 使用 apiVersion、种类和元数据字段将字段标记为嵌入式资源。并与preserve-unknown-fields: true结合不会修剪该字段,并且该字段里面包含一个完整的对象。
+kubebuilder:validation:Enum:=
指定此(标量)字段仅限于此处指定的 Enum值。
+kubebuilder:validation:ExclusiveMaximum:=
表示最大值“达到”但不包括该值。
+kubebuilder:validation:ExclusiveMinimum:=
表示最小值“达到”但不包括该值。
+kubebuilder:validation:Format:=
指定字段类型
+kubebuilder:validation:MaxItems:=
指定此列表的最大长度。
+kubebuilder:validation:MaxLength:=
指定此字符串的最大长度。
+kubebuilder:validation:MaxProperties:=
限制对象中键的数量
+kubebuilder:validation:MinItems:=
指定此列表的最小长度
+kubebuilder:validation:MinLength:=
指定此字符串的最小长度。
+kubebuilder:validation:MinProperties:=
限制对象中键的数量
+kubebuilder:validation:Minimum:=
指定此字段可以具有的最小数值。支持负整数。
+kubebuilder:validation:MultipleOf:=
指定此字段必须具有一个数值,该数值是该数值的倍数。
+kubebuilder:validation:Optional
如果默认情况下需要字段,则指定此字段是可选的。
+kubebuilder:validation:Pattern:=
指定此字符串必须匹配给定的正则表达式。
+kubebuilder:validation:Required
如果默认情况下字段是可选的,则指定此字段是必需的。
+kubebuilder:validation:Type:=
覆盖该字段的类型(默认为 Go 类型的等价物)。这通常必须与自定义序列化配对。例如,metav1.Time 字段将被标记为“type: string”和“format: date-time”。
+kubebuilder:validation:UniqueItems:=
指定此列表中的所有项目都必须是唯一的。
+kubebuilder:validation:XEmbeddedResource
同上EmbeddedResource
+nullable
将此字段标记为允许“空”值。
+optional
如果默认情况下需要字段,则指定此字段是可选的。
+kubebuilder:validation:Schemaless
将字段标记为无模式对象。无模式对象不会自省,因此您必须自己提供任何类型和验证信息。此标记的一种用途是嵌入包含 JSONSchema 类型对象的字段。由于此字段禁用所有类型检查,因此建议仅作为最后的手段使用。
CRD Processing
+kubebuilder:pruning:PreserveUnknownFields
阻止字段修剪,当调用资源时,会对资源进行校验,校验失败的会自动删除,该字段可以设置是否删除。
+kubebuilder:validation:XPreserveUnknownFields
同上,已被上面取代。
+listMapKey:=
指定映射 listTypes 的键。它表示map的索引。如果必须使用多个键,则可以重复它们。只能在 ListType 设置为 map 时使用,并且键应该是标量类型。
+listType:=
指定列表表示的数据结构的类型(映射、集合、原子)。
列表的可能数据结构类型有:
“map”:需要有一个key字段,用来构建关联列表。一个典型的例子是 pod 容器列表,它由容器名称索引。
“set”:字段必须是“标量”,并且每个字段只能出现一次。
“atomic”:列表中的所有字段都被视为单个值,通常由同一个参与者一起操作。
+mapType:=
指定map的原子性级别;
即map中的每个项目是否独立于其他项目,或者所有字段都被视为一个单元。
可能的值:
“granular”:map中的项目相互独立,可以由不同的参与者操作。这是默认行为。
“atomic”:所有字段都被视为一个单元。任何更改都必须替换整个map。
+structType:=
指定结构的原子性级别;
即结构中的每个字段是否独立于其他字段,或者所有字段都被视为一个单元。
可能的值:
“granular”:结构中的字段相互独立,可以由不同的参与者操作。这是默认行为。
“atomic”:所有字段都被视为一个单元。任何更改都必须替换整个结构。
WebHook
例子:
//+kubebuilder:webhook:path=/mutate-v1-pod,mutating=true,failurePolicy=fail,groups="",resources=pods,verbs=create;update,versions=v1,name=mpod.kb.io
这些标记描述了如何生成webhook 配置。
+kubebuilder:webhook:admissionReviewVersions=<[]string>,failurePolicy=<string>,groups=<[]string>,matchPolicy=<string>,mutating=<bool>,name=<string>,path=<string>,resources=<[]string>,sideEffects=<string>,verbs=<[]string>,versions=<[]string>,webhookVersions=<[]string>
- admissionReviewVersions=:<[]string>
是 Webhook 期望的首选 AdmissionReview
版本的有序列表。对于生成 v1 {Mutating,Validating}WebhookConfiguration,这是强制性的。用于生成 v1beta1 {Mutating,Validating}WebhookConfiguration,这是可选的,默认为 v1beta1。
- failurePolicy=:
指定如果 API 服务器无法访问 webhook 时的策略
它可能是“ignore”(跳过 webhook 并继续)或“fail”(拒绝有问题的对象)。
-
groups=:<[]string>
指定此 Webhook 接收请求的 API 组。
-
matchPolicy=:
定义如何使用“规则”列表来匹配传入的请求。允许的值为“Exact”(仅当它与指定的规则完全匹配时才匹配)或“Equivalent”(如果它修改了规则中列出的资源,甚至通过另一个 API 组或版本,则匹配请求)。
-
mutating=:
启动mutating webhook
-
name=:
表示此 webhook 配置的名称
-
path=:
指定 API 服务器应连接到此 webhook 的路径。必须以“/validate-”或“/mutate-”作为前缀,具体取决于类型,然后是 G R O U P − GROUP- GROUP−VERSION-$KIND,其中所有值都小写,组中的句点替换为连字符。
-
resources=:<[]string>
设置监控的api资源 例如:deployments。
-
sideEffects=:
风险评估,如果值为“None”,则 Webhook 没有风险,API 服务器将在试运行时调用它。如果值为“NoneOnDryRun”,则 webhook 负责检查请求中发送的 AdmissionReview 的“dryRun”属性,并在该值为“true”时避免副作用。
-
verbs=:<[]string>
指定此 webhook 接收请求的 Kubernetes API 动作。可以是“create”、“update”、“delete”、“connect”或“*”(适用于所有)。
-
versions=:<[]string>
指定此 webhook 接收请求的 API 版本
-
webhookVersions=:<[]string>
指定要生成的 {Mutating,Validating}WebhookConfiguration 对象本身的目标 API 版本。默认为 v1。
Object/DeepCopy
这些标记控制何时DeepCopy
生成runtime.Object
实现方法。
+kubebuilder:object:generate:=
覆盖启用或禁用此类型的深拷贝生成
+kubebuilder:object:root:=
启用此类型的对象接口实现生成
+kubebuilder:object:generate:=
启用或禁用此包的对象接口和 deepcopy 实现生成
RBAC
会根据配置生成role.yaml以及rolebinding.yaml文件,并生成sa.yaml。
例子:
// +kubebuilder:rbac:groups=servicemanager.servicemanager.io,resources=servicemanagers,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=servicemanager.servicemanager.io,resources=servicemanagers/status,verbs=get;update;patch
+kubebuilder:rbac
//+kubebuilder:rbac:groups=<[]string>,namespace=<string>,resourceNames=<[]string>,resourcess=<[]tring>,urls=<[]string>,verbs=<[]string>
-
groups:=<[]string>
指定api 组 比如 deployment 属于apps组
-
namespace:=
指定作用的命名空间,如果未指定则是Cluster,这影响生成的是role还是ClusterRole
-
resourceNames:=<[]string>
指定此规则包含的 API 资源的名称。
-
resources:=<[]string>
指定此规则包含的 API 资源 比如deployments资源
-
urls:=<[]string>
配置访问非资源的URL
-
verbs:=<[]string>
对资源的操作,比如get;list;watch;create;update;patch
更多推荐
所有评论(0)