开发者工具代码生成CLI云原生后端【免费下载链接】kubebuilderKubebuilder - SDK for building Kubernetes APIs using CRDs项目地址https://gitcode.com/gh_mirrors/ku/kubebuilder点击查看免费下载本篇技术指南系统讲解 Kubebuilder 项目中如何通过// kubebuilder:xxx形式的 marker 注释从 Go 类型与包中构造 CustomResourceDefinitionCRD的原理与实战用法。文中内容基于本仓库docs/book/src/reference/markers/crd.md所对应的 CRD 生成标记体系并结合controller-gen的实际调用链与仓库内真实项目testdata/project-v4的生成产物展开。读完本文你将掌握 CRD 结构标记、验证标记、打印列、子资源、多版本存储等完整配置技能并能自行解读make manifests生成的 CRD YAML。CRD 标记是什么从 Go 类型构造 CRD 的核心机制在 Kubebuilder 项目中CRD 并非手写 YAML而是由controller-gen工具从 Go 类型自动生成。controller-gen通过解析源码中特殊的标记注释以// 开头的注释行来获知每个字段、类型和包的附加信息进而构造出 OpenAPI v3 结构的验证 schema 与 CRD 的各个部分。本仓库文档 crd.md 开篇即点明这些标记的核心定位These markers describe how to construct a custom resource definition from a series of Go types and packages.也就是说CRD 生成标记CRD Generation markers负责描述如何从一系列 Go 类型和包构造 CRD而实际验证 schema 的生成则由 验证标记validation markers 负责。两者分工明确前者决定 CRD 的结构形态资源路径、作用域、版本、打印列、子资源等后者决定字段级的校验约束。标记文档的生成机制模板注入而非静态书写值得注意的是crd.md正文中{{#markerdocs CRD}}是一个模板占位符其实际内容由仓库中的文档生成工具注入。在 markerdocs/main.go 中可以看到MarkerDocs插件会执行controller-gen并解析其-wwww输出 JSON从中提取每个 marker 的名称、参数类型与帮助说明再替换到{{#markerdocs category}}位置参见 main.go 中的 getMarkerDocs 与 Process 实现。具体运行时通过 markerdocs.sh 构建并执行。因此CRD 标记的官方参考本质上是 controller-gen 输出的实时帮助信息与所安装的 controller-tools 版本严格对应。标记的基本语法在深入各类 CRD 标记之前先掌握 marker 的三种形态详见 markers.md空标记Empty如同命令行布尔开关写上即启用行为例如// kubebuilder:validation:Optional、// kubebuilder:subresource:status。匿名标记Anonymous接受单个值作为参数例如// kubebuilder:validation:MaxItems2。多选项标记Multi-option接受一个或多个具名参数第一个参数与名字之间用冒号分隔后续参数以逗号分隔参数顺序无关紧要部分参数可省略例如// kubebuilder:printcolumn:JSONPath.status.replicas,nameReplicas,typestring标记参数支持字符串、整数、布尔、切片与映射。字符串、整数、布尔遵循 Go 语法简单单字符串可省略引号如// kubebuilder:validation:Typestring复杂字符串建议加引号切片可用花括号逗号分隔或简单场景下用分号分隔如// kubebuilder:validation:EnumWallace;Gromit;Chicken映射使用{key: value, ...}形式如// kubebuilder:default{magic: {numero: 42, stringified: forty-two}}。运行入口make manifests 与 controller-genKubebuilder 通过make manifests目标驱动controller-gen生成 CRD。以仓库中的真实样例项目为例testdata/project-v4/Makefile 中的目标为manifests: controller-gen $(CONTROLLER_GEN) rbac:roleNamemanager-role crd webhook applyconfiguration:headerFilehack/boilerplate.go.txt paths./... output:crd:artifacts:configconfig/crd/bases关键点拆解crd是 controller-gen 的一个 generator生成器负责读取_types.go中的标记并产出 CRD YAMLpaths./...指定扫描全部 Go 包output:crd:artifacts:configconfig/crd/bases是输出规则output rule把 CRD 相关的非代码产物输出到config/crd/bases目录而不是默认的config/crd同一命令中还一并生成 RBACrbac:roleNamemanager-role与 Webhook 配置webhook。controller-gen的每个生成器都由与 marker 相同语法的选项控制也支持不同的输出规则。如果想查看全部生成器与选项可运行controller-gen -h # 更详细的信息 controller-gen -hhhKubebuilder 生成的 Makefile 会在本地bin/目录LOCALBIN按需安装 controller-gen本仓库样例固定版本为CONTROLLER_TOOLS_VERSION ? v0.22.0见 testdata/project-v4/Makefile无需手动全局安装。生成产物位于config/crd/bases且会在 CRD 注解中记录controller-gen.kubebuilder.io/version便于追溯生成工具版本可在 testdata/project-v4/config/crd/bases/crew.testproject.org_admirales.yaml 中看到controller-gen.kubebuilder.io/version: v0.22.0。资源结构标记resourcekubebuilder:resource标记用于控制 CRD 在 Kubernetes 中的资源形态包括path资源复数路径与scopeNamespaced 或 Cluster。例如仓库测试数据 admiral_types.go 中的用法// kubebuilder:object:roottrue // kubebuilder:ac:generatefalse // kubebuilder:subresource:status // kubebuilder:resource:pathadmirales,scopeCluster // Admiral is the Schema for the admirales API type Admiral struct { metav1.TypeMeta json:,inline metav1.ObjectMeta json:metadata,omitzero Spec AdmiralSpec json:spec Status AdmiralStatus json:status,omitzero }这里pathadmirales声明了 CRD 的 resource 名对应 YAML 中的plural与names: plural字段scopeCluster表示集群级资源。与之对照navigator_types.go 中则使用// kubebuilder:resource:pathnavigators且未指定 scope即默认的 Namespaced。若省略pathcontroller-gen 会根据类型名自动推导复数形式。生成的 YAML 中可看到对应的scope与names字段。验证标记validationCRD 支持使用 OpenAPI v3 schema 进行声明式校验校验规则通过 验证标记 附加到字段或类型上。每个验证标记大致对应一个 OpenAPI/JSON schema 选项。对于复杂校验、需复用校验或需校验切片元素时最推荐的做法是定义一个新类型来承载校验参见 generating-crd.md。一个综合示例type ToySpec struct { // kubebuilder:validation:MaxLength15 // kubebuilder:validation:MinLength1 Name string json:name,omitempty // kubebuilder:validation:MaxItems500 // kubebuilder:validation:MinItems1 // kubebuilder:validation:UniqueItemstrue Knights []string json:knights,omitempty Alias Alias json:alias,omitempty Rank Rank json:rank } // kubebuilder:validation:EnumLion;Wolf;Dragon type Alias string // kubebuilder:validation:Minimum1 // kubebuilder:validation:Maximum3 // kubebuilder:validation:ExclusiveMaximumfalse type Rank int32要点说明字段级验证直接写在字段上方MaxLength/MinLength约束字符串长度MaxItems/MinItems约束切片元素数量UniqueItems要求切片元素唯一类型级验证写在类型定义上方Enum限定合法取值集合多个取值用分号分隔Minimum/Maximum/ExclusiveMaximum限定数值范围通过为自定义类型附加标记同一套校验可被多个字段复用也能对切片元素生效自定义资源实际由 API server 依据生成的 OpenAPI v3 schema 进行校验且必须符合 Kubernetes 结构式 schemastructural schema规则。数值类型应尽量映射到 OpenAPI 支持良好的 Go 类型如int32、int64需要十进制类表示时优先使用resource.Quantity。关于kubebuilder:validation:Optional与// optional的差异见 markers.md 的说明两者都能作用于字段但kubebuilder:validation:Optional还可用于包级别使包内所有字段生效若只为 controller-gen 服务二者等价但若要兼容其他生成器或让开发者自行构建客户端建议同时保留optional。在 1.x 中获取optional最可靠的方式是使用omitempty。附加打印列printcolumn自 Kubernetes 1.11 起kubectl get可向服务端查询要显示的列。CRD 通过additionalPrinterColumns字段控制kubectl get的输出而该字段由 Go 类型上的kubebuilder:printcolumn标记控制。延续上面的示例为 Toy 类型添加打印列// kubebuilder:printcolumn:nameAlias,typestring,JSONPath.spec.alias // kubebuilder:printcolumn:nameRank,typeinteger,JSONPath.spec.rank // kubebuilder:printcolumn:nameBravely Run Away,typeboolean,JSONPath.spec.knights[?( Sir Robin)],descriptionwhen danger rears its ugly head, he bravely turned his tail and fled,priority10 // kubebuilder:printcolumn:nameAge,typedate,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 }参数解析name列显示名称type列数据类型支持string、integer、boolean、date等JSONPath从资源中提取列值的 JSONPath 表达式如.spec.alias、.metadata.creationTimestampdescription列的描述说明可选priority列的显示优先级非零值列默认在-o wide输出中才显示可选。这些标记最终会映射为生成 CRD YAML 中的additionalPrinterColumns数组。子资源subresource自 Kubernetes 1.13 起CRD 可以选择实现/status与/scale子资源。官方强烈建议所有带 status 字段的资源都启用/status子资源。两者都有对应的标记详见 generating-crd.md 的 Subresources 一节。status 子资源通过// kubebuilder:subresource:status启用。启用后对主资源的更新不会改变 status对 status 子资源的更新也只能修改 status 字段二者隔离避免控制器与其他写入方互相覆盖。示例// kubebuilder:subresource:status type Toy struct { metav1.TypeMeta json:,inline metav1.ObjectMeta json:metadata,omitempty Spec ToySpec json:spec,omitempty Status ToyStatus json:status,omitempty }在仓库测试数据 captain_types.go 中同样可见// kubebuilder:subresource:status的标准用法。scale 子资源通过// kubebuilder:subresource:scale启用需要三个参数specpath指向 spec 中副本数字段的 JSONPath如.spec.replicasstatuspath指向 status 中副本数字段的 JSONPath如.status.replicasselectorpath可选指向标签选择器字符串形式字段的 JSONPath如.status.selector。若该字段是标签选择器的字符串形式HorizontalPodAutoscaler 便可据此自动扩缩该资源。示例type CustomSetSpec struct { Replicas *int32 json:replicas } type CustomSetStatus struct { Replicas int32 json:replicas Selector string json:selector // 必须是选择器的字符串形式 } // kubebuilder:subresource:status // kubebuilder:subresource:scale:specpath.spec.replicas,statuspath.status.replicas,selectorpath.status.selector type CustomSet struct { metav1.TypeMeta json:,inline metav1.ObjectMeta json:metadata,omitempty Spec CustomSetSpec json:spec,omitempty Status CustomSetStatus json:status,omitempty }生成的 CRD YAML 中对应subresources小节。仓库生成产物 crew.testproject.org_admirales.yaml 中可看到storage: true与subresources:并存的形态。多版本与存储版本storageversion自 Kubernetes 1.13 起CRD 可以定义 Kind 的多个版本并通过 Webhook 在版本间转换。多版本 CRD 的完整流程参见 多版本教程。默认情况下Kubebuilder 出于对旧版 Kubernetes 的兼容会为 CRD 关闭不同版本不同验证的能力。若要启用需要修改 Makefile 中的CRD_OPTIONS使用 v1beta CRD 时从CRD_OPTIONS ? crd:trivialVersionstrue,preserveUnknownFieldsfalse改为CRD_OPTIONS ? crd:preserveUnknownFieldsfalse使用 v1推荐时改为CRD_OPTIONS ? crd。随后使用kubebuilder:storageversion标记指明应由 API server 用于存储数据的 Group-Version-KindGVK。每个 Kind 有且只能有一个版本被标记为存储版本。仓库测试数据中即有典型范例firstmate_types.go v1 带有// kubebuilder:storageversion而 v2 版本 未加该标记。对照生成的 CRD YAML crew.testproject.org_firstmates.yaml 与 #L234可看到 v1 版本storage: true、v2 版本storage: false。多版本间的转换函数则由kubebuilder:conversion相关标记与手动编写的转换 Webhook 配合完成仓库 firstmate_conversion.go 与 v2 版 即为转换实现样例。常见组合模式一个完整 CRD 类型的标记布局综合以上内容一个生产级 CRD 类型通常按如下模式组织标记自上而下依次为包级/列表、类型级结构、子资源、资源形态、存储版本、打印列、字段验证// kubebuilder:object:roottrue // kubebuilder:subresource:status // kubebuilder:resource:pathtoys,scopeNamespaced // kubebuilder:storageversion // kubebuilder:printcolumn:nameAge,typedate,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:object:roottrue // ToyList contains a list of Toy type ToyList struct { metav1.TypeMeta json:,inline metav1.ListMeta json:metadata,omitempty Items []Toy json:items }kubebuilder:object:roottrue与对应的ToyList配合使类型可作为runtime.Object注册进 scheme同时驱动 DeepCopy 代码生成修改_types.go后需重新运行make manifests重新生成 CRD与make generate重新生成 DeepCopy 等代码文件头部的注释Important: Run make to regenerate code after modifying this file即为提醒可见于 admiral_types.go。验证与排错生成后检查产物CRD 位于config/crd/bases下命名形如group_resource.yaml可通过make install安装到集群内部先kustomize build config/crd再kubectl apply见 testdata/project-v4/Makefile。查看 controller-gen 全部选项运行controller-gen -h概要或controller-gen -hhh详细信息。直接调用 controller-gen若不想走 Makefile可手动执行$(CONTROLLER_GEN) crd paths./... output:crd:artifacts:configconfig/crd/bases观察其行为参见 generating-crd.md 的 Under the hood 一节。标记文档的动态性由于 CRD 标记参考由 controller-gen 实时输出注入若你安装的 controller-tools 版本与仓库样例不同个别标记的可用性可能略有差异请以controller-gen crd -www的输出为准。延伸阅读CRD 验证标记字段与类型的 OpenAPI v3 校验约束全集生成 CRD 全流程validation、printer columns、subresources、多版本与底层机制的系统讲解Markers 总览marker 语法、make manifests/make generate分工与optional细节多版本转换教程hub-spoke 转换模型与 Webhook 落地控制器生成器参考controller-gen 工具本身的用法真实样例project-v4 测试项目 与 project-v4-multigroup 测试项目其中包含 CRD 标记、转换函数与多版本组织的一手素材。赞分享开发者工具代码生成CLI云原生后端【免费下载链接】kubebuilderKubebuilder - SDK for building Kubernetes APIs using CRDs项目地址https://gitcode.com/gh_mirrors/ku/kubebuilder点击查看免费下载相关推荐SymPy 拉普拉斯变换从“暴力积分”到规则表驱动引擎的设计与实现解析SymPy 拉普拉斯变换从“暴力积分”到规则表驱动引擎的设计与实现解析 本文以 SymPy 官方设计文档《Laplace Transform: Design开发者工具代码生成CLI云原生后端Kubebuilder Markers标记大全8大类注解驱动CRD与RBAC代码生成速查Kubebuilder Markers标记大全8大类注解驱动CRD与RBAC代码生成速查 Kubebuilder 是构建 Kubernetes APICRD开发者工具代码生成CLI云原生后端Kubebuilder CRD 校验标记Validation Markers完全指南用 OpenAPI v3 Schema 声明式约束你的自定义资源Kubebuilder CRD 校验标记Validation Markers完全指南用 OpenAPI v3 Schema 声明式约束你的自定义资源 本文开发者工具代码生成CLI云原生后端上一篇Rainmeter 音乐可视化器快速指南Monstercat Visualizer 让桌面随音乐跳动下一篇WSABuilds 更新到 GApps 版后 Play Store 提示无法连接 play.google.com 怎么登录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
