controller-runtime 与 CRD 控制器开发实战

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.example.com
spec:
  group: example.com
  scope: Namespaced
  names:
    kind: Database
    plural: databases
    shortNames: ["db"]
  versions:
    - name: v1
      served: true
      storage: true
      subresources:
        status: {}
      additionalPrinterColumns:
        - name: Engine
          type: string
          jsonPath: .spec.engine
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required: ["engine", "sizeGB"]
              properties:
                engine:
                  type: string
                  enum: ["postgres", "mysql"]
                sizeGB:
                  type: integer
                  minimum: 1
                replicas:
                  type: integer
                  default: 1

第一层：OpenAPI schema（类型、枚举、必填、范围）—— 零成本，优先用
第二层：CEL 校验规则（x-kubernetes-validations）—— 支持跨字段表达式
第三层：ValidatingAdmissionWebhook —— 需要外部数据时才用

x-kubernetes-validations:
  - rule: "self.replicas <= 5 || self.engine == 'postgres'"
    message: "仅 postgres 支持超过 5 副本"

Manager
 ├── Cache (informer 共享)  ← 所有 Controller 复用
 ├── Client (读写入口，读走 Cache)
 ├── Scheme (GVK 与 Go 类型互转)
 ├── Leader Election (多副本只有一个 Active)
 └── Controllers (DatabaseReconciler / BackupReconciler)

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
    Scheme:           scheme,
    LeaderElection:   true,
    LeaderElectionID: "database-operator.example.com",
})
if err != nil {
    os.Exit(1)
}
if err = (&DatabaseReconciler{Client: mgr.GetClient(), Scheme: mgr.GetScheme()}).
    SetupWithManager(mgr); err != nil {
    os.Exit(1)
}
mgr.AddHealthzCheck("healthz", healthz.Ping)
if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
    os.Exit(1)
}

func (r *DatabaseReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var db examplev1.Database
    if err := r.Get(ctx, req.NamespacedName, &db); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)  // 已删除属正常
    }
    // 1. 观测现实并写 status  2. 对比期望与实际
    // 3. 采取行动             4. 更新 status.conditions
    return ctrl.Result{}, nil
}

patch := client.MergeFrom(db.DeepCopy())
db.Spec.Replicas = desired
if err := r.Patch(ctx, &db, patch); err != nil {
    return ctrl.Result{}, err
}

return ctrl.Result{}, nil                成功，等待下次事件
return ctrl.Result{}, err                失败，指数退避重试
return ctrl.Result{RequeueAfter: 30*time.Second}, nil   延迟重入

return ctrl.NewControllerManagedBy(mgr).
    For(&examplev1.Database{}).
    Owns(&appsv1.StatefulSet{}).
    Owns(&corev1.Service{}).
    WithEventFilter(predicate.GenerationChangedPredicate{}).
    Complete(r)

WithEventFilter(predicate.Or(
    predicate.GenerationChangedPredicate{},   // spec 变更
    predicate.LabelChangedPredicate{},        // 标签变更
    predicate.AnnotationChangedPredicate{},   // 注解变更
))

if err := ctrl.SetControllerReference(db, sts, r.Scheme); err != nil {
    return ctrl.Result{}, err
}

Foreground：先删子对象，父对象保持 finalizer 直到子对象全删完
Background：立即删父对象，GC 异步清理子对象（默认）
Orphan：只删父对象，子对象保留

kubectl delete database my-db --cascade=foreground

const dbFinalizer = "database.example.com/finalizer"

if db.DeletionTimestamp.IsZero() {
    if !controllerutil.ContainsFinalizer(&db, dbFinalizer) {
        controllerutil.AddFinalizer(&db, dbFinalizer)
        return ctrl.Result{}, r.Update(ctx, &db)   // 先落库，再做别的
    }
} else {
    if controllerutil.ContainsFinalizer(&db, dbFinalizer) {
        if err := r.deleteExternalResources(ctx, &db); err != nil {
            return ctrl.Result{}, err   // 清理失败保留 finalizer，稍后重试
        }
        controllerutil.RemoveFinalizer(&db, dbFinalizer)
        return ctrl.Result{}, r.Update(ctx, &db)
    }
    return ctrl.Result{}, nil
}

□ 首次 Reconcile 先加 finalizer，再创建任何外部资源
□ 删除路径先清外部资源，全部成功后再移除 finalizer
□ 清理逻辑必须幂等（资源不存在视为成功），并设置超时

if !reflect.DeepEqual(db.Status, newStatus) {
    db.Status = newStatus
    if err := r.Status().Update(ctx, &db); err != nil {
        return ctrl.Result{}, err
    }
}

status:
  conditions:
    - type: Ready
      status: "True"
      reason: ProvisionSucceeded
      message: "数据库实例已就绪"
      observedGeneration: 3
      lastTransitionTime: "2026-10-02T02:00:00Z"

meta.SetStatusCondition(&db.Status.Conditions, metav1.Condition{
    Type:               "Ready",
    Status:             metav1.ConditionTrue,
    Reason:             "ProvisionSucceeded",
    ObservedGeneration: db.Generation,
})

make test        # 跑单元测试（含 envtest）
make manifests   # 重新生成 CRD YAML 与 RBAC
make run         # 本地对真实集群跑控制器

□ CRD 启用 status 子资源与 additionalPrinterColumns
□ 所有外部资源创建前先加 Finalizer
□ Reconcile 全程幂等，可被任意次重入
□ 用 Patch 而非 Update 降低冲突
□ 谓词过滤掉 status 变更，避免自触发
□ 条件带 observedGeneration，便于判断新旧
□ 控制器多副本 + Leader Election + PDB
□ RBAC 最小权限，用 kubebuilder 注解生成