kubebuilder工作流程

---

Kubebuilder 工作流程詳解

Kubebuilder 是 Kubernetes 官方推薦的 Operator 開發框架，用于構建基于 Custom Resource Definitions (CRD) 的控制器。以下是其核心工作流程的完整說明：

---

1. 初始化項目

# 創建項目目錄
mkdir my-operator && cd my-operator# 初始化 Kubebuilder 項目（指定 Go 模塊名和 Kubernetes API 版本）
kubebuilder init --domain my.domain.com --repo my.domain.com/my-operator# 創建 API（定義 CRD 和控制器）
kubebuilder create api --group webapp --version v1 --kind Guestbook

作用：

• 生成項目腳手架代碼
• 配置 go.mod 和基礎 Makefile
• 創建 CRD 的 API 類型定義（api/v1/guestbook_types.go）

---

2. 設計 CRD (Custom Resource)

編輯生成的 API 類型文件 api/v1/guestbook_types.go：

type GuestbookSpec struct {// 定義用戶可配置字段Message string `json:"message"`Replicas int32 `json:"replicas"`
}type GuestbookStatus struct {// 定義控制器維護的狀態字段AvailableReplicas int32 `json:"availableReplicas"`
}

關鍵操作：

• 實現 runtime.Object 接口（Kubebuilder 已自動生成）
• 通過 // +kubebuilder:subresource:status 等標記擴展功能

---

3. 生成 CRD 和代碼

# 生成 CRD YAML 和 DeepCopy 方法
make manifests# 生成客戶端代碼（如 informers、listers）
make generate

輸出結果：

• config/crd/bases/ 下的 CRD YAML 文件
• zz_generated.deepcopy.go 自動生成的深拷貝代碼

---

4. 實現控制器邏輯

編輯 controllers/guestbook_controller.go：

func (r *GuestbookReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {// 1. 獲取 CR 實例guestbook := &webappv1.Guestbook{}if err := r.Get(ctx, req.NamespacedName, guestbook); err != nil {return ctrl.Result{}, client.IgnoreNotFound(err)}// 2. 業務邏輯（例如創建 Deployment）dep := &appsv1.Deployment{}if err := r.Get(ctx, req.NamespacedName, dep); err != nil {if errors.IsNotFound(err) {// 創建 Deploymentdep = r.newDeploymentForGuestbook(guestbook)if err := r.Create(ctx, dep); err != nil {return ctrl.Result{}, err}}}// 3. 更新狀態guestbook.Status.AvailableReplicas = dep.Status.AvailableReplicasif err := r.Status().Update(ctx, guestbook); err != nil {return ctrl.Result{}, err}return ctrl.Result{}, nil
}

核心機制：

• Reconcile 循環：監聽 CR 變化并觸發調諧邏輯
• 冪等性設計：確保重復執行不會產生副作用

---

5. 本地測試

# 安裝 CRD 到集群
make install# 運行控制器（本地開發模式）
make run# 部署示例 CR
kubectl apply -f config/samples/webapp_v1_guestbook.yaml

調試工具：

• 使用 kubectl get guestbooks 查看自定義資源
• 通過 kubectl logs 查看控制器日志

---

6. 構建與部署

# 構建鏡像
make docker-build docker-push IMG=my-registry/my-operator:v1.0.0# 生成部署清單（RBAC、Deployment 等）
make manifests# 部署到集群
make deploy IMG=my-registry/my-operator:v1.0.0

生成內容：

• config/rbac/：角色權限配置
• config/manager/：Operator 的 Deployment 配置

---

7. 高級功能擴展

Webhook 支持

# 創建 webhook
kubebuilder create webhook --group webapp --version v1 --kind Guestbook --defaulting --programmatic-validation

用途：

• 實現字段默認值注入（Mutating Webhook）
• 驗證字段合法性（Validating Webhook）

多版本 API 支持

通過 kubebuilder edit --multiversion 開啟，生成版本轉換邏輯。

---

工作流程圖解

---

關鍵設計理念

1. 聲明式 API：用戶通過 YAML 描述期望狀態，控制器負責實現
2. 事件驅動：基于 Kubernetes 的 Informer 機制高效監聽資源變更
3. 水平擴展：控制器可多副本運行，通過 Leader Election 避免沖突

Kubebuilder 通過標準化的工作流程，顯著降低了 Operator 的開發門檻，是構建 Kubernetes 原生擴展組件的首選工具。