全网最详细的Kubebuilder开发K8s Operator的全流程指南，细致入微（真不标题党！）

Go 版本 v1.23.0+
您已安装的 Docker 版本为 17.03 或更高
kubectl 版本 v1.11.3 及以上
访问 Kubernetes v1.11.3+ 集群
准备远程开发环境连接 Linux 系统，Kubebuilder 没有提供 Windows 版本安装。配置远程开发环境文字教程：https://mp.weixin.qq.com/s/EYxaUznVaAIWSUvEkeILLA

3）安装 Go

安装 Go 环境：https://www.cnblogs.com/niuben/p/16801294.html

安装 Go 之后，配置下载包的代理，避免下载 Go 依赖包失败。

Go 代理官网：https://goproxy.cn/、https://goproxy.io/zh/

echo "export GO111MODULE=on" >> ~/.profile
echo "export GOPROXY=https://goproxy.cn" >> ~/.profile
source ~/.profile

4）安装 Kubebuilder

下载地址：https://github.com/kubernetes-sigs/kubebuilder/releases

mv kubebuilder_linux_amd64  kubebuilder && chmod +x kubebuilder && mv kubebuilder /usr/local/bin/

初始化 kububuilder 项目工程

创建工作目录

mkdir -p /opt/code/kubebuilder-zcyw-demo
cd /opt/code/kubebuilder-zcyw-demo

创建一个 Operator 项目

# 创建 mod
go mod init github.com/yjcadmin/kubebuilder-zcyw-demo
# 初始化 kubebuilder
kubebuilder init --domain zcywapp.test
# 创建自定义资源的api和控制器
kubebuilder create api --group zcywapp --version v1beta1 --kind Zcywwebapp

项目生成文件解读

Kubebuilder 工程的核心流程是：

在 api/zcywwebapp_types.go 定义 CRD 的 API 结构；
在 internal/controller/*_controller.go 实现 Reconcile 调和逻辑；
通过 Makefile 生成代码、配置；
通过 config/ 目录的 YAML 将 CRD 和控制器部署到 Kubernetes 集群中运行。

目录结构

开发 CRD

设计 CRD

你都看到这里了，再告诉你一个99%的人都不知道的密码，双击屏幕有惊喜哦！！

设计 CRD 主要是修改zcywwebapp_types.go文件，根据自己的 Operator 要实现的功能定义属性字段（见下图）。

这里要实现的功能是，可以通过 CRD 来自动创建 Deployment 并且选择是否也自动创建对应的 Service 和 Ingress。定义如下：

EnableIngress # 是否自动创建 Ingress
EnableService # 是否自动创建 Service
Replicas # 控制 Deployment 副本数
Image # 控制 Deployment 的镜像

同时可以看到图中由于修改了zcywwebapp_types.go文件后，zz_generated.deepcopy.go就提示了有报错，这个时候需要通过命令重新生成一些描述和代码。

生成 CRD 相关代码

make 是构建自动化工具同时也是一个命令行工具，用于自动化执行一系列命令，通过读取 Makefile 文件中的规则来决定执行什么操作。

我们通过 make 提供的相关命令：

make manifests命令重新生成修改后的 CRD 定义描述。如：Kubernetes清单文件、CRD、RBAC、Webhook 配置等。
make generate 命令重新生成代码。生成客户端代码（Client/DeepCopy/Informer/Lister 等）、更新 CRD 相关的 Go 代码、运行 controller-gen 工具生成代码。修改了 API 类型（修改了*_types.go文件），添加/修改了结构体的字段就需要重新生成 *.deepcopy.go 接口实现。

# 执行make命令前，进入到项目的工作目录
cd /opt/code/kubebuilder-zcyw-demo

# 生成Kubernetes清单文件、CRD、RBAC、Webhook 配置等
make manifests

# 该命令执行后，zz_generated.deepcopy.go 就不会提示报错了，如下图：
make generate

安装 CRD

上一步，我们已经生成了 CRD 项目代码。接着我们就可以执行 make install和 make uninstall 来安装卸载 CRD 了。

我们可以查看工程目录下的 Makefile 文件中是存在 install 和 uninstall 命令的。

cd /opt/code/kubebuilder-zcyw-demo

# 将 CRD 安装到 Kubernetes 集群
make install

# 运行自定义的 CR 资源
kubectl apply -f ./config/samples/zcywapp_v1beta1_zcywwebapp.yaml

kubectl apply运行ingress_v1beta1_app.yaml时报错了，这里我们还需要为该文件添加我们在zcywwebapp_types.go文件中定义的属性

zcywapp_v1beta1_zcywwebapp.yaml文件中添加的字段与zcywwebapp_types.go文件中定义的属性字段，不是一模一样，但是意思是一一对应的。

再次安装 CRD

cd /opt/code/kubebuilder-zcyw-demo

# 将 CRD 安装到 Kubernetes 集群
make install

# 运行自定义的 CR 资源
kubectl apply -f ./config/samples/zcywapp_v1beta1_zcywwebapp.yaml

验证 CRD

查看我们自定义的 CRD 和 CR 是否安装完成

kubectl get Zcywwebapp
kubectl get crd | grep zcywapp

开发 Controller

Operator 是对 K8s 资源（自定义或内置的资源）的扩展编程或者说开发一个资源对象，就像：Pod、Deploy、Service 一样。

Controller 工作原理

Controller 是面向期望的编程模型，可以理解 Deployment 期望的副本个数一个道理。

工作流程：List&Watch -》Delta FIFO Queue -》Index&Local Store -》Delta FIFO Queue -》WordQueue -》 Controller -》Local Store

List&Watch：获取数据，监听事件
Index&Local Store：将数据存储在缓存中，存储前也需要经过Delta FIFO Queue阶段
Delta FIFO Queue：队列优化，避免重复事件（update、create、delete），为 api-server 减少压力
WordQueue：获取index&local store阶段缓存数据中对象的 key
Controller：通过 WordQueue 得到的 key 来判断核心逻辑，同时调用 Local Store中的缓存数据，该 key 是否存在缓存中，如果存在那么就让他变成期望的状态（期望状态是 WordQueue 获取的 key 对象的状态）。如果从WordQueue来的 key 在Local Store取不到说明该对象删除了，需要执行删除逻辑

主要还是写 Controller 阶段的业务逻辑，其他阶段逻辑其实感知不到的，被 Kubebuilder 封装了。

解读 `*_controller.go` 文件

业务编写逻辑都在 internal/controller 目录下，一般都会以 *_controller.go 命名规则来命名，作为核心的业务逻辑编写。

1）Reconcile方法：凡事外部的对象有变化，都调用这个Reconcile方法来通知你，所以这里可以根据事件编写业务逻辑。

2）SetupWithManager方法：这个 Controller 要被跑起来，需要将该 Controller 注册给 Manager 才能跑起来，而这个SetupWithManager方法也是实现这个功能的入口。

SetupWithManager方法这里 Watch 了一个 CRD 的对象，是我们默认生成的那个 CRD 对象。

也可以 Watch 其他对象，比如，Pod、Service、Deployment、Ingress。如图：

编写业务逻辑代码

这里将以这个仓库中的业务逻辑代码作为演示：https://github.com/baidingtech/operator-lesson-demo/tree/main/kubebuilder-demo，如下图：

复制上述app_controller.go文件中的业务逻辑中的代码到我这里的zcywwebapp_controller.go，再根据自己实现的情况，需要稍作修改。解决一些依赖、路径问题（需要懂 Go 基础语法）。

# 生成Kubernetes清单文件、CRD、RBAC、Webhook 配置等
make manifests

# 该命令执行后，zz_generated.deepcopy.go 就不会提示报错了，如下图：
make generate

测试 Controller

启动项目前，确保已安装 CRD 和自定义的 CR 资源

cd /opt/code/kubebuilder-zcyw-demo
make install
kubectl apply -f ./config/samples/zcywapp_v1beta1_zcywwebapp.yaml

本地启动 Kubebuilder 工程

# 前台启动
make run

# 后台启动
make run &

自动创建了 Deployment、Service

打开 Ingress 的启用开关那么将会自动创建 Ingress

Deployment、Service、Ingress 均通过 CRD 控制实现自动创建

部署 Controller

本地调试通之后，接着打包镜像来部署。

构建镜像

需要安装 Docker。apt install docker.io

make docker-build IMG=registry.cn-chengdu.aliyuncs.com/qiuyl01/zcywapp-controller:v1.3
# 也可采用
docker build -t registry.cn-chengdu.aliyuncs.com/qiuyl01/zcywapp-controller:v1.3 .

Push 镜像

# make docker-push IMG=registry.cn-chengdu.aliyuncs.com/qiuyl01/zcywapp-controller:v1
docker push registry.cn-chengdu.aliyuncs.com/qiuyl01/zcywapp-controller:v1.3

部署

部署之前需要在zcywwebapp_controller.go文件中添加图中的注解。这些注解是Kubebuilder RBAC标记，用于自动生成 Kubernetes 的基于角色的访问控制(RBAC)规则。

//+kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
//+kubebuilder:rbac:groups=networking.k8s.io,resources=ingresses,verbs=get;list;watch;create;update;patch;delete
//+kubebuilder:rbac:groups="",resources=services,verbs=get;list;watch;create;update;patch;delete

执行部署命令，部署 CRD 和 Controller。

make deploy 是 Kubebuilder 项目中用于部署控制器到 Kubernetes 集群的核心命令。它将构建好的镜像部署到目标集群，创建所有必要的 Kubernetes 资源。

# 部署 CRD 和 Controller
make deploy IMG=registry.cn-chengdu.aliyuncs.com/qiuyl01/zcywapp-controller:v1.3

# 删除部署的 CRD 和 Controller 的命令
make undeploy

验证

创建我们的 CR 资源

kubectl apply -f ./config/samples/zcywapp_v1beta1_zcywwebapp.yaml

由于enable_ingress、enable_service均为true，所以我们的自定义ZcywwebappCRD 资源会根据 CR 中的配置自动创建下图中的，Deployment、Service、Ingress。

Kustomize 导出部署的资源文件

通过上面make deploy方式进行部署，用户在使用 Operator 时还需要拉取完整代码仓库并基于源码执行部署命令，显然在正式使用的过程中并不友好，所以需要将 make deploy 所依赖的所有部署资源（CRD、RBAC、Deployment 等）整合为单个 YAML 文件，简化用户的部署流程。

要将 Kubebuilder 项目中 make deploy 部署的所有资源合并到一个 YAML 文件，核心是利用 Kubebuilder 内置的 Kustomize 工具（make deploy 底层依赖 Kustomize 构建资源），将 Kustomize 构建后的所有资源输出并保存为单个 YAML 文件。

1）安装 kustomize

kustomize 下载地址：https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv5.8.0

tar -xf kustomize_v5.8.0_linux_amd64.tar.gz &&  mv kustomize /usr/local/bin/

2）使用 kustomize 生成

kustomize build config/default > all-in-one-deploy.yaml

3）kubectl 命令运行 all-in-one.yaml

kubectl apply -f all-in-one.yaml

4）验证 CRD 功能

cd /opt/code/kubebuilder-zcyw-demo

# 运行CR
kubectl apply -f ./config/samples/zcywapp_v1beta1_zcywwebapp.yaml

可以看到我们的 CRD 功能依旧正常

过程中出现的问题

1）问题描述：镜像build构建时，无法将除了go.mod、go.sum的文件和目录拷贝到容器中

处理方法：将.dockerignore文件修改为其他名称。这个文件作用是，用于告诉 Docker 在构建镜像时忽略哪些文件和目录。

2）问题描述：执行 kubebuilder create api报错，当前使用的kububuilder-v3.10.0。

处理方法：使用最新的kububuilder-v4.10.1版本后执行成功。

3）问题描述：make deploy启动服务时报错，没有 Deployment、Service、Ingress 相关权限。

处理方法：在zcywwebapp_controller.go文件中添加图中的注解。这些注解是 Kubebuilder RBAC 标记，用于自动生成 Kubernetes 的基于角色的访问控制(RBAC)规则。

4）问题描述：启动项目时准备的模板文件系统找不到，这里是 Dockerfile 构建时没有将该模板目录复制进入运行的容器。

处理方法：

解决文件不存在问题：Dockerfile 文件中执行启动命令前添加COPY internal/controller/template/ internal/controller/template/
解决添加文件后无权限问题：去掉或注释 Dockerfile 中的 USER 65532:65532

Dockerfile 参考直接去我提交的 GitHub 仓库

至此，你已经完成了 kububuilder 项目开发 Operator 的完整流程，我相信你对 kububuilder 已经有了不少的认识，剩下的业务逻辑代码编写部分是需要根据工作中不断提高的能力，也就是代码编程能力。

参考

https://kubebuilder.cn/quick-start.html

https://github.com/baidingtech/operator-lesson-demo/blob/main/kubebuilder-demo/docs/%E5%AE%9E%E7%8E%B0controller%E9%80%BB%E8%BE%91.md

https://www.bilibili.com/video/BV14M4y1R7Qr?t=1523.6&p=2

https://blog.csdn.net/boling_cavalry/article/details/113840999