Kubernetes 1.29 自定义资源（CRD）开发与控制器实战

1. CRD 核心概念

自定义资源（CRD）是扩展 Kubernetes API 的核心机制，允许用户定义自己的资源类型。其核心关系可表示为： $$ \text{CRD} \rightarrow \text{API 扩展} \rightarrow \text{自定义资源对象} $$ 其中：

• CRD 定义：声明资源类型（如 MyApp）
• CR 实例：具体资源配置（如 my-app-instance）

2. 开发流程

步骤 1：创建 CRD 定义

# myapp-crd.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myapps.example.com
spec:
  group: example.com
  names:
    kind: MyApp
    plural: myapps
  scope: Namespaced
  versions:
    - name: v1alpha1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas: 
                  type: integer
                image:
                  type: string

步骤 2：实现自定义控制器 控制器通过监听事件实现调和循环（Reconciliation Loop）：

// 控制器核心逻辑框架
func (c *Controller) Run(stopCh <-chan struct{}) {
  informer := cache.NewSharedIndexInformer(...)
  informer.AddEventHandler(cache.ResourceEventHandlerFuncs{
    AddFunc:    c.onAdd,
    UpdateFunc: c.onUpdate,
    DeleteFunc: c.onDelete,
  })
  
  go informer.Run(stopCh)
  
  // 启动工作协程
  for i := 0; i < workers; i++ {
    go wait.Until(c.worker, time.Second, stopCh)
  }
}

// 调和函数示例
func (c *Controller) reconcile(obj *v1alpha1.MyApp) error {
  // 1. 检查当前状态
  // 2. 对比期望状态
  // 3. 执行操作（创建/更新/删除资源）
  if obj.Spec.Replicas != currentDeployment.Status.Replicas {
    c.kubeClient.AppsV1().Deployments(...).Update(...)
  }
}

3. 关键开发技巧

a. 控制器优化模式

• 使用工作队列处理事件
• 实现指数退避重试
• 添加Finalizers确保资源清理

b. 代码生成工具 使用 kubebuilder 或 operator-sdk 加速开发：

operator-sdk init --domain example.com --repo github.com/example/my-operator
operator-sdk create api --group apps --version v1alpha1 --kind MyApp

c. 测试策略

• 使用envtest进行Kubernetes API集成测试
• 模拟客户端测试控制器逻辑：

fakeClient := clientfake.NewClientBuilder().
    WithObjects(testMyApp).
    Build()
reconciler.Reconcile(ctx, reconcile.Request{...})

4. 1.29 版本新特性

• CRD 验证改进：增强 OpenAPIv3 模式验证
• 服务器端应用（SSA） 支持：kubectl apply --server-side
• 警告机制：在 CRD 过时时返回 API 警告

5. 实战示例：简易应用部署器

CR 实例

apiVersion: example.com/v1alpha1
kind: MyApp
metadata:
  name: demo-app
spec:
  replicas: 3
  image: nginx:1.25

控制器操作逻辑

func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
  myApp := &v1alpha1.MyApp{}
  if err := r.Get(ctx, req.NamespacedName, myApp); err != nil {
    return ctrl.Result{}, client.IgnoreNotFound(err)
  }
  
  // 创建对应的Deployment
  dep := &appsv1.Deployment{
    Spec: appsv1.DeploymentSpec{
      Replicas: &myApp.Spec.Replicas,
      Template: corev1.PodTemplateSpec{
        Spec: corev1.PodSpec{
          Containers: []corev1.Container{{
            Image: myApp.Spec.Image,
          }},
        },
      },
    },
  }
  
  // 应用Server-Side Apply
  if err := r.Patch(ctx, dep, client.Apply, client.FieldOwner("myapp-controller")); err != nil {
    return ctrl.Result{}, err
  }
  
  return ctrl.Result{}, nil
}

6. 部署与调试

部署控制器

kubectl apply -f myapp-crd.yaml
go build -o operator && ./operator

调试命令

# 查看CRD
kubectl get crd myapps.example.com -o yaml

# 检查控制器日志
kubectl logs -l control-plane=controller-manager

7. 最佳实践

• 版本管理：遵循 $v1alpha1 \rightarrow v1beta1 \rightarrow v1$ 演进路径
• RBAC 配置：为控制器配置最小权限
• 指标暴露：实现 /metrics 端点监控调和延迟
• Leader 选举：确保多副本高可用

通过以上流程，可实现生产级 CRD 扩展，典型应用场景包括数据库算子、AI工作流调度器等。开发中需重点关注调和循环的幂等性和错误处理能力。