作者: mmwei3
郵箱: 1300042631@qq.com / mmwei3@iflytek.com
日期: 2025年08月16日
項目地址: GitHub - PyJob Operator
CSDN博客: 從零開始構建Kubernetes Operator

一、引言

在云原生時代，Kubernetes已經成為容器編排的事實標準。然而，當我們面臨復雜的業務場景，特別是需要管理有狀態服務時，原生的Kubernetes資源往往顯得力不從心。今天，我將分享如何從零開始構建一個完整的Kubernetes Operator，用于管理深度學習訓練任務。

這個PyJob Operator項目是一個完整的、生產就緒的Kubernetes Operator實現，它不僅展示了Operator開發的最佳實踐，還提供了豐富的示例和詳細的文檔。無論是學習Kubernetes Operator開發，還是作為實際項目的起點，都具有很高的價值。可以幫助SRE和運維開發工程師們在運維的海洋里盡情擴展定制。這也是我入手的第一個operator實現，給我帶來了很大的啟發，也是因為這個我學習了contorller和operator的區別以及理解有狀態和無狀態的區別，包括哪些適合daemonset，不需要早輪子，哪些是需要定制開發的場景，如果你也剛好接觸operator可以一起交流，1300042631@qq.com。
這個operator的開發和2022年時在云計算研究院二次開發openstack-nova/cinder/ironic組件還是不太一樣的，不過都能學習到很多優秀的邏輯和思維以及異常處理，我認為思想非常重要，因為思想決定目標。

二、為什么需要Operator？

1. Controller vs Operator：本質區別

在深入開發之前，我們需要理解Controller和Operator的核心區別：

Controller（控制器）：

• 管理單一資源類型的基礎生命周期
• 通過調和循環確保實際狀態向期望狀態收斂
• 適用于無狀態服務的簡單場景

Operator（操作器）：

• 封裝復雜應用的自動化運維邏輯
• 將運維專家的知識編碼到Kubernetes中
• 特別適合有狀態服務的復雜場景

2. 有狀態服務 vs 無狀態服務的挑戰

無狀態服務：

# 使用Deployment管理，Pod可以隨意調度/重建
apiVersion: apps/v1
kind: Deployment
spec:replicas: 3template:spec:containers:- name: nginximage: nginx:1.20

有狀態服務（如訓練任務）：

• 需要GPU資源調度
• 需要持久化存儲
• 需要狀態監控和故障恢復
• 需要復雜的生命周期管理

這就是為什么我們需要Operator的原因！

三、項目架構設計

3.1整體架構圖

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   PyJob CRD     │───?│  PyJob Controller│───?│  Kubernetes Job │
└─────────────────┘    └──────────────────┘    └─────────────────┘│                        │                        │▼                        ▼                        ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   User Input    │    │  Reconcile Loop  │    │   Pod Creation  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

3.2核心組件

1. PyJob CRD：自定義資源定義，描述訓練任務的期望狀態
2. PyJob Controller：控制器，負責調和實際狀態和期望狀態
3. Kubernetes Job：底層Kubernetes資源，實際執行訓練任務
4. PersistentVolumeClaim：持久化存儲，存儲數據和模型

4.核心實現解析

1. CRD定義 - 聲明式API設計

// PyJobSpec 定義用戶期望的任務配置
type PyJobSpec struct {Image   string   `json:"image"`           // 訓練鏡像Command []string `json:"command"`         // 執行命令GPU     int32    `json:"gpu"`             // GPU數量DatasetPath string `json:"datasetPath"`   // 數據集路徑OutputPath string `json:"outputPath"`     // 輸出路徑Resources *ResourceRequirements `json:"resources"` // 資源限制
}// PyJobStatus 記錄任務狀態
type PyJobStatus struct {Phase   string `json:"phase"`             // 任務階段Message string `json:"message"`           // 狀態信息StartTime *metav1.Time `json:"startTime"` // 開始時間CompletionTime *metav1.Time `json:"completionTime"` // 完成時間
}

2. Controller實現 - 調和循環核心

func (r *PyJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {// 1. 獲取PyJob實例var pyjob trainingv1.PyJobif err := r.Get(ctx, req.NamespacedName, &pyjob); err != nil {return ctrl.Result{}, err}// 2. 檢查是否需要創建JobjobName := fmt.Sprintf("%s-job", pyjob.Name)var job batchv1.Joberr := r.Get(ctx, types.NamespacedName{Name: jobName, Namespace: pyjob.Namespace}, &job)if err != nil && errors.IsNotFound(err) {// 3. 創建新的Jobif err := r.createJob(ctx, &pyjob, jobName); err != nil {return ctrl.Result{}, err}// 4. 更新狀態pyjob.Status.Phase = "Running"r.Status().Update(ctx, &pyjob)}// 5. 監控Job狀態并更新PyJobreturn r.updatePyJobStatus(ctx, &pyjob, &job)
}

3. GPU資源調度 - 智能資源管理

// 創建包含GPU資源的Job
func (r *PyJobReconciler) createJob(ctx context.Context, pyjob *trainingv1.PyJob, jobName string) error {// 配置GPU資源if pyjob.Spec.GPU > 0 {resourceRequirements.Limits["nvidia.com/gpu"] = *resource.NewQuantity(int64(pyjob.Spec.GPU), resource.DecimalSI)}// 創建Pod模板container := corev1.Container{Name:    "trainer",Image:   pyjob.Spec.Image,Command: pyjob.Spec.Command,Resources: resourceRequirements,}// 創建Job資源job := &batchv1.Job{ObjectMeta: metav1.ObjectMeta{Name:      jobName,Namespace: pyjob.Namespace,},Spec: batchv1.JobSpec{Template: corev1.PodTemplateSpec{Spec: corev1.PodSpec{Containers: []corev1.Container{container},},},},}return r.Create(ctx, job)
}

五、實際使用場景

場景1：簡單訓練任務

apiVersion: training.example.com/v1
kind: PyJob
metadata:name: bert-training
spec:image: "pytorch/pytorch:2.0-cuda11.7-cudnn8-devel"command: ["python", "train_bert.py"]gpu: 1resources:cpu: "4"memory: "8Gi"

傳統方式需要創建：

• ConfigMap（訓練腳本）
• Job（訓練任務）
• Service（日志收集）
• PVC（數據存儲）

Operator方式只需要：

• 一個PyJob資源！

場景2：分布式多GPU訓練

apiVersion: training.example.com/v1
kind: PyJob
metadata:name: distributed-training
spec:image: "pytorch/pytorch:2.0-cuda11.7-cudnn8-devel"command: - "python"- "train_distributed.py"- "--world-size=4"gpu: 4datasetPath: "/mnt/dataset"outputPath: "/mnt/output"resources:cpu: "16"memory: "32Gi"

Operator自動處理：

• GPU資源調度
• 分布式訓練配置
• 存儲卷掛載
• 狀態監控

六、開發經驗分享

1. 項目結構設計

k8s_operator_train/
├── api/v1/                    # API定義
│   ├── pyjob_types.go        # 資源結構定義
│   └── groupversion_info.go  # API版本信息
├── controllers/               # Controller實現
│   └── pyjob_controller.go   # 核心業務邏輯
├── config/                   # 部署配置
│   ├── crd/                 # CRD定義
│   ├── rbac/                # 權限配置
│   └── manager/             # 部署配置
├── examples/                # 使用示例
└── scripts/                 # 構建腳本

2. 開發工具鏈

• Kubebuilder：Operator開發框架
• controller-runtime：Controller運行時
• Kustomize：配置管理
• Docker：容器化部署

3. 調試技巧

# 本地開發調試
make run# 查看資源狀態
kubectl get pyjobs
kubectl describe pyjob <name># 查看Controller日志
kubectl logs -n system deployment/pyjob-controller-manager# 查看事件
kubectl get events --sort-by=.metadata.creationTimestamp

七、部署和使用

快速部署

# 1. 克隆項目
git clone git@github.com:pwxwmm/k8s_operator_train.git
cd k8s_operator_train# 2. 構建和部署
./scripts/dev-setup.sh
./scripts/build.sh
./scripts/deploy.sh# 3. 運行示例
kubectl apply -f examples/simple-training.yaml# 4. 查看狀態
kubectl get pyjobs

八、監控和管理

# 查看所有訓練任務
kubectl get pyjobs -A# 監控任務狀態
kubectl get pyjob <name> -w# 查看任務日志
kubectl logs -l pyjob-name=<name># 刪除任務
kubectl delete pyjob <name>

九、項目亮點

1. 完整的生產就緒特性

• ? RBAC權限控制：安全的資源訪問
• ? 狀態監控：實時任務狀態跟蹤
• ? 錯誤處理：自動重試和故障恢復
• ? 資源管理：智能的GPU和存儲調度
• ? 可擴展性：支持復雜的訓練場景

2. 豐富的使用示例

• 簡單訓練任務
• 多GPU分布式訓練
• 帶持久化存儲的訓練
• 自定義資源配置

3. 完善的文檔

• 詳細的README文檔
• 快速開始指南
• 開發文檔
• 故障排除指南

十、技術收獲

1. Kubernetes擴展開發

• 深入理解CRD和Controller機制
• 掌握Operator開發最佳實踐
• 學習云原生架構設計模式

2. Go語言實踐

• 大型項目的代碼組織
• 并發編程和錯誤處理
• 測試和調試技巧

3. 運維自動化

• 將運維知識編碼到系統中
• 聲明式API設計
• 自動化運維流程

通過這個項目，我們實現了一個完整的Kubernetes Operator，它展示了如何：

1. 簡化復雜操作：將多個Kubernetes資源的創建和管理抽象為一個PyJob資源
2. 自動化運維：自動處理GPU調度、存儲管理、狀態監控等復雜邏輯
3. 提升用戶體驗：用戶只需要定義期望狀態，Operator自動處理實現細節
4. 保證可靠性：通過調和循環確保系統始終處于期望狀態

這正是Operator模式的核心價值：將運維專家的知識編碼到Kubernetes中，讓復雜的應用管理變得簡單可靠。我認為這也是聲明式的一個探索吧

十一、下一步計劃

• 添加Webhook驗證功能
• 集成Prometheus監控
• 支持多集群訓練
• 添加工作流編排能力

---

---

項目地址: GitHub - PyJob Operator
CSDN博客: 從零開始構建Kubernetes Operator
聯系方式: 1300042631@qq.com / mmwei3@iflytek.com

如果你對這個項目感興趣，歡迎Star、Fork和提交Issue！讓我們一起推動云原生技術的發展！ 🚀

---

本文首發于CSDN技術博客，轉載請注明出處。