kubebuilder 总结 | Forrest’s 博客

🏹kubebuilder 总结

type

Post

status

Published

date

Apr 27, 2025

slug

kubebuilder

summary

kuberbuilder是什么

Kubebuilder 是一个用于构建 Kubernetes API 和控制器的框架

基本概念

为了更好的使用kubebuilder，可以先看看一下的基础概念。

CRD是什么

CRD（Custom Resource Definition）是k8s中扩展API的方式，它允许你定义一种新的资源类型，看起来和k8s中原生的资源一样。

Controller是什么

Controller负责不断检查集群中的资源对象是否符合预期（Spec），对其不断的协调（reconcile）。

Operator 是什么

Operator是通过自定义资源（CRD）和自定义的控制器（controller），实现对应用的自动化管理。

k8s中资源表示符 GVK 和 GVR

在k8s中，GVK（Group, Version, Kind）和 GVR（Group, Version, Resource）是用于标识和访问 Kubernetes 资源的两个重要概念。

Group：API 组的名称。例如，apps 组包含 Deployment、StatefulSet 等资源，batch 组包含 Job、CronJob 等资源。

Version：API 版本。每个资源在 Kubernetes 中可能会有多个版本（如 v1、v1beta1、v1alpha1 等），每个版本可能会有不同的功能和行为

Kind：资源的类型。通常是资源的单数形式，如 Pod、Deployment、Service。

Resource：资源的名称。通常是复数形式，如 pods、deployments、services

具体区别：

GVK 里的 Kind 是单数；GVR 里的 Resource 是复数

GVK用于标识k8s资源的类型，资源的序列化和反序列化；GVR用于标识 k8s Restful API的端点，适用于client-go 访问k8s资源

声明式的API

k8s 使用声明式API，所谓声明式就是“你告诉k8s你想要什么，而不是告诉他具体如何做什么命令”

利用kubebuilder进行Operator的开发

大体的开发步骤

使用kubebuilder 初始化项目

创建api对象，填写spec和status

实现controller

创建webhook（可选）

本地开发调试

构建镜像并生成部署manifest

安装kubebuilder

项目初始化

你的 API Group 最终会是 <resource-name>.<version>.<domain>，例如 application.v1.crd.forrest.com

创建 API对象

创建webhook（可选

make相关的指令

本地开发和调试

构建和部署

reconcile的大体架构模式

一个典型的 Reconcile 实现通常包含以下主要步骤：

细节部分

OwnerReference 的使用

用途：实现资源的级联删除和自动触发调谐

实现方式：使用 controllerutil.SetControllerReference(&app, &deploy, r.Scheme)

好处：

自动级联删除子资源
子资源变更自动触发 owner 的调谐
简化代码逻辑

Finalizers 的使用

用途：确保资源删除前进行必要的清理工作

关键逻辑：

新建资源时添加 Finalizer
删除时先执行清理，再移除 Finalizer

实现建议：

Event 记录

在Reconciler对象上增加 Recorder字段

同时，启动时初始化

建议：只记录重要节点的事件，避免过多事件影响集群性能

实现方式：

Watching resources

除了设置OwnerReference，从而来自动监听子资源，也可以手动设置watch的资源是什么。

Watching Secondary Resources that are NOT Owned（如何监听不是子资源的变更

通过 EnqueueRequestsFromMapFunc 从 Deploy 触发 Application。

这里的逻辑是：如果一个带有app label的Deployment发送变化时，controller会自动触发AppService的reconcile。这是一种补充机制，用于处理那些可能与AppService 相关，但不是通过 OwnerReference 直接关联的 Deployment 资源。