search
GitHub

快速开始

hashtag
安装kubebuilder

安装说明可查看kubebuilder官方文档arrow-up-right。

hashtag
快速开始

安装好 kubebuilder 后，运行以下命令，将新 API（组/版本）创建为 webapp/v1，并在其中创建新的 Kind（CRD）Guestbook。

// 初始化一个kubebuilder项目
kubebuilder init --domain go17 --repo="operator" --owner="ayo"

kubebuilder create api --group webapp --version v1 --kind Guestbook

命令运行后会有两个可选项供选择

如果按下 y 来创建资源 [y/n] 和创建控制器 [y/n]，那么这将创建文件 api/v1/guestbook_types.go，其中定义了 API，并在 internal/controllers/guestbook_controller.go 中实现了对此 Kind(CRD) 的协调业务逻辑。

选项说明：

命令
选项
核心作用
在项目中的主要体现位置

**kubebuilder init**​

--domain go17

定义 API 组的域名后缀，是 CRD 全名的组成部分。

PROJECT文件；后续生成的 CRD 组名（如 webapp.go17）。

--repo="operator"

指定项目的 Go 模块路径，用于依赖管理。

go.mod文件；main.go等代码文件中的导入路径。

--owner="ayohuang"

(可选) 记录项目维护者信息。

PROJECT文件。

**kubebuilder create api**​

--group webapp

指定 API 的组名，与 --domain共同构成完整的 API 组。

生成的 API 代码目录结构（如 apis/webapp/v1/）；CRD 定义中的组名（webapp.go17）。

--version v1

定义 API 的版本。遵循 Kubernetes API 版本规范（如 v1alpha1, v1beta1, v1）。

生成的 API 代码目录结构（如 apis/webapp/v1/）；CRD 定义中的版本字段。

--kind Guestbook

定义自定义资源（CR）的种类，即资源类型的名称。大写字母开头。

生成的 Go 结构体名称（如 type Guestbook struct）；CRD 定义中的 Kind 字段。

hashtag
关注文件

执行完后会生成一堆脚手架文件，主要关注以下几个文件即可：

api/v1alpha1/<kind>_types.go —— 资源的“长相”

这是你定义“自定义资源 (CRD)”的地方。

  • 为什么要关注： Kubernetes 不知道你的应用需要多少内存、什么镜像。你得在这里定义你的“协议”。

  • 里面有什么：

    • Spec (期望状态)：用户在 YAML 里填写的字段。比如 Replicas int32（我要 3 个副本）。

    • Status (实际状态)：Operator 观察到的结果。比如 AvailableReplicas int32（目前集群里实际只有 2 个）。

  • 怎么用： 你在这里增加字段（比如加一个 Image 字符串字段），运行 make manifests 后，Kubebuilder 会自动生成对应的 YAML 给 K8s 看。

internal/controller/<kind>_controller.go —— 资源的“大脑”

这是你编写 90% 业务逻辑的地方，也是整个 Operator 的灵魂。

  • 为什么要关注： 它是那个永远在跑的死循环。当用户创建或修改了资源，这个文件里的代码就会被触发。

  • 里面有哪些关键点：

    • Reconcile 函数：这是你的战场。你在这里写代码：检查 Pod 够不够？不够就补，多了就删。

    • +kubebuilder:rbac 注解：这行注释非常重要！它决定了你的 Operator 有没有权限去“创建 Pod”或“删除 Service”。如果你漏写了，代码会报 Permission Denied。

    • SetupWithManager：它告诉系统：“请盯着这个资源，一旦有变动就叫醒我”。

main.go —— 工程的“总调度室”

这是整个程序的入口。

  • 为什么要关注： 虽然大部分代码是生成的，但如果你想增加一些特殊的全局设置（比如多集群支持、设置监控端口），就在这里。

  • 里面有什么：

    • Manager (管理者)：它就像一个管家，负责管理底层的缓存（Cache）和客户端。

    • 初始化逻辑：它负责把你的 Controller 注册到 Manager 中并启动。

  • 怎么用： 初学者通常只需要观察它是如何把 api 和 controller 串联起来的，轻易不要大幅修改。

Makefile —— 你的“自动化管家”

它不是 Go 代码，但它是你最常用的“遥控器”。

  • 为什么要关注： Operator 开发涉及很多辅助操作（生成代码、安装 CRD、部署镜像），手动敲命令会累死人。

  • 里面有哪些常用指令：

    • make manifests：根据你在 _types.go 里的修改，自动生成最新的 CRD YAML 文件。

    • make install：把你的自定义资源定义（CRD）一键安装到 Minikube 集群里。

    • make run：在本地直接运行你的 Operator 进程（不需要打成镜像，方便调试逻辑）。

PROJECT —— 工程的“户口本”

  • 为什么要关注： 这是一个简单的 YAML 文件，记录了你项目的 Domain、Group、Version 等基本信息。

  • 里面有什么： 它记录了你已经创建了哪些 API。如果你之后想用 kubebuilder create api 增加第二个自定义资源，Kubebuilder 会读取这个文件来确保一致性。

hashtag
make命令

kuberbuiler 会提供一整个命令集合，方便快速集成和调试。

类别
核心命令
主要功能

**开发 (Development)**​

manifests, generate, test

生成代码/配置、格式化、测试代码质量。

**构建 (Build)**​

build, run, docker-build

编译二进制文件、构建容器镜像。

**部署 (Deployment)**​

install, deploy

将CRD和Operator控制器安装到K8s集群。

依赖管理​

kustomize, controller-gen

下载和管理项目所需的工具。

  • 开发与测试

    • make manifests: 这是最关键的命令之一。当您修改完 API 定义（如 api/v1/guestbook_types.go文件）后，需要运行此命令。它会根据代码中的注解（如 //+kubebuilder:subresource:status）生成或更新 CustomResourceDefinition (CRD) 的 YAML 清单文件，这些文件位于 config/crd/bases/目录下。

    • make generate: 另一个关键命令。在修改 API 定义后，它会生成包含 DeepCopy等方法的运行时辅助代码（如 zz_generated.deepcopy.go），这些代码对于 Kubernetes API 的运作是必需的。

    • make test: 运行项目的单元测试和集成测试。集成测试会启动一个临时的 Kubernetes 测试环境（API 服务器和 etcd）。

    • make fmt/ make vet: 分别用于代码格式化和静态分析，是保证代码规范的佳实践。

  • 构建与运行

    • make build: 编译项目，生成可执行的 Manager 二进制文件。

    • make run: 在本地开发环境中启动 Operator。它会使用您的 ~/.kube/config文件连接到集群，非常适合快速迭代和调试。

    • make docker-build: 根据 Dockerfile构建 Operator 的容器镜像。需要使用 IMG=<your-image-tag>参数指定镜像名称和标签。

    • make docker-push: 将构建好的镜像推送到远程镜像仓库（如 Docker Hub、Quay.io）。

  • 部署到集群

    • make install: 将 config/crd/bases/目录下生成的 CRD 安装到当前 kubeconfig指向的 Kubernetes 集群中。在部署 Operator 前必须先执行此步骤。

    • make deploy: 生成 Operator 的部署清单（包括 Deployment、RBAC 等）并将其部署到集群中。同样需要使用 IMG=<your-image-tag>参数指定要使用的镜像。

一个典型的 Operator 开发、构建和部署流程如下：

  1. 修改 API：编辑 *_types.go文件，定义您的自定义资源规格（Spec）和状态（Status）。

  2. 生成代码与配置：运行 make manifests generate来生成 CRD 和运行时代码。

  3. 实现协调逻辑：在 *_controller.go文件的 Reconcile函数中编写业务逻辑。

  4. 本地测试：使用 make install安装 CRD，然后使用 make run在本地运行 Operator 进行测试。

  5. 构建与推送镜像：使用 make docker-build docker-push IMG=your-repo/your-operator:v1.0.0准备容器镜像。

  6. 正式部署：使用 make deploy IMG=your-repo/your-operator:v1.0.0将 Operator 部署到目标集群。

上一页实现一个CronJob下一页简单包学习

最后更新于