kubebuilder-标记注释

导读KubeBuilder 使用称为controller-gen生成实用程序代码和 Kubernetes 对象 YAML 的工具，例如 CustomResourceDefinitions。为此，它使用特殊的“标记注释”（以开头的注释// +）来指示有关字段、类型和包的附加信息。kubebuilder的标记注释官网讲解那么接下来让我们开始走进 “标记注释”CRD生成关于CRD生成时的可以进行的配置

迷茫路人

2925人浏览 · 2022-02-10 13:47:38

迷茫路人 · 2022-02-10 13:47:38 发布

导读

KubeBuilder 使用称为controller-gen生成实用程序代码和 Kubernetes 对象 YAML 的工具，例如 CustomResourceDefinitions。

为此，它使用特殊的“标记注释”（以开头的注释// +）来指示有关字段、类型和包的附加信息。

kubebuilder的标记注释官网讲解

那么接下来让我们开始走进 “标记注释”

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 指labelSelectorPathScale 对象的属性，该值jsonpath定义了对应的自定义资源内部的 JSONPath Scale.Status.Selector。这是个可选的选项。
statuspath 指statusReplicasPathScale 对象的属性。并且jsonpath它的值定义了对应于Scale.Status.Replicas. 这是一个必填字段。
specpath 指specReplicasPathScale 对象的属性，valuejsonpath定义了对应的自定义资源内部的 JSONPath Scale.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 -$ 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

Cloudpods

开源、云原生的融合云平台

更多推荐

面向未来的 IT 基础设施管理架构——融合云（Unified IaaS）

随着数字化时代的到来，IT系统已成为人类社会正常运转不可或缺的组成部分。不远的未来，智能制造，5G和人工智能等技术将成为推动生产力发展的重要引擎，人类社会将面临前所未有的全面彻底的数字化浪潮。IT基础设施作为IT系统运行的平台和载体，是实现数字化的基石。在这场数字化浪潮中，企业必须积极拥抱云计算技术，采用符合技术发展趋势、面向未来的IT基础构架，才能在未来的竞争中赢得先机。一、云计算历经十余年

Cloudpods

Cloudpods负载均衡的功能介绍

作者:周有松今天的内容会从以下几个方面展开：负载均衡产品简介。主要介绍负载均衡作为一个云上产品，它的功能模型是怎样的，日常使用中会遇到的业务词汇负载均衡的功能与典型应用场景。这部分主要结合业务词汇，对负载均衡服务中常见的一些功能选项进行介绍，并举例介绍一些典型的应用场景最后，我们做一下总结，讨论一下负载均衡产品相比传统方式的优点一、产品简介 1. 以NGINX为例提到负载均衡，我们以

Cloudpods

使用Linux vfio将Nvidia GPU透传给QEMU虚拟机

Linux 上虚拟机 GPU 透传需要使用 vfio 的方式。主要是因为在 vfio 方式下对虚拟设备的权限和 DMA 隔离上做的更好。但是这么做也有个缺点，这个物理设备在主机和其他虚拟机都不能使用了。 qemu 直接使用物理设备本身命令行是很简单的，关键在于事先在主机上对系统、内核和物理设备的一些配置。单纯从 qemu 的命令行来看，其实和普通虚拟机启动就差了最后那个-device的选项。这