📚 课程目录第2章 Kubernetes Operator基础回顾

2. Kubernetes Operator 基础回顾：Operator SDK 项目结构、Reconcile 循环与 Controller-Runtime 核心接口

在深入多租户幂等控制隔离策略之前，必须重新夯实 Operator 开发的核心基础。本章聚焦于 Operator SDK（kubebuilder / operator-sdk） 的标准项目布局、Reconcile 循环 的执行语义以及 controller-runtime 库的核心接口。这些知识是后续构建控制面蓝图的技术基石。

2.1 Operator SDK 项目结构

无论是使用 kubebuilder 还是 operator-sdk 脚手架，生成的项目结构高度一致。下表列出了关键目录与文件的作用：

目录 / 文件	作用	多租户场景关注点
`api/<version>/`	定义 CRD（CustomResourceDefinition）的 Go 结构体，包含 Spec 与 Status	需在 Spec 中显式声明 `TenantID` 字段，用于隔离
`controllers/`	存放 Reconcile 循环实现，每个 Kind 对应一个 `Reconciler`	Reconciler 内必须注入租户上下文校验逻辑
`config/crd/`	生成的 CRD YAML 清单，包含验证规则与版本转换	可添加 `x-kubernetes-validations` 做租户字段预检
`config/rbac/`	RBAC 规则，定义 ServiceAccount 对资源的操作权限	需按租户粒度拆分 ClusterRole 或使用 `resourceAttributes`
`internal/`	可选，存放非导出的工具包、租户缓存、幂等令牌管理	推荐将租户隔离的辅助函数放在此处，避免循环依赖
`main.go`	程序入口，初始化 Manager、注册 Scheme、启动 Controller	在此注入多租户的 `Manager.Options` 与租户感知的 `Client`

最佳实践： 在多租户 Operator 中，api/ 层的结构体应包含 TenantID string `json:"tenantID"`，并在 config/crd/ 中通过 +kubebuilder:validation:Required 标记为必填，从 API 入口强制隔离。

2.2 Reconcile 循环：幂等与重试语义

Reconcile 循环是 Operator 的核心执行单元。controller-runtime 保证每个 Reconcile 请求是幂等的，即多次执行相同输入应产生相同结果。下图展示了标准 Reconcile 循环的流程：

  幂等实现要点：
  读取-修改-写入模式： 使用 client.Get 获取最新版本，修改后使用 client.Update 或 client.Status().Update，依赖 resourceVersion 做乐观锁。
状态收敛： 每次 Reconcile 都从当前实际状态出发，向期望状态收敛，而非基于上一次操作的结果。
错误处理： 返回 ctrl.Result{RequeueAfter: 5 * time.Second} 避免重试风暴；对于不可恢复错误，记录 Event 后返回 nil。

2.3 Controller-Runtime 核心接口

controller-runtime 提供了四个核心接口，Operator 开发者必须深入理解：

接口	定义位置	核心方法	多租户隔离中的作用
`manager.Manager`	`sigs.k8s.io/controller-runtime/pkg/manager`	`Start()`, `GetClient()`, `GetCache()`	管理 Controller 生命周期；可注入租户感知的 `Cache` 与 `Client`
`reconcile.Reconciler`	`sigs.k8s.io/controller-runtime/pkg/reconcile`	`Reconcile(context.Context, Request) (Result, error)`	每个租户的资源变更都会触发此方法；需在方法内校验 `TenantID`
`controller.Controller`	`sigs.k8s.io/controller-runtime/pkg/controller`	`Watch()`, `Start()`	定义监听哪些资源；可配置 `MaxConcurrentReconciles` 控制并发
`source.Source`	`sigs.k8s.io/controller-runtime/pkg/source`	`Start()`, `Stop()`	事件源，支持 `Kind`、`Channel`、`Informer`；多租户下需过滤无关事件

2.4 典型 Reconciler 实现骨架

以下代码展示了一个标准 Reconciler 的结构，包含租户 ID 校验与幂等更新：

import (
    "context"
    "fmt"

    "k8s.io/apimachinery/pkg/api/errors"
    "k8s.io/apimachinery/pkg/runtime"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/log"

    examplev1 "your.domain/api/v1"
)

// TenantAwareReconciler 为多租户场景设计的 Reconciler
type TenantAwareReconciler struct {
    client.Client
    Scheme *runtime.Scheme
}

// +kubebuilder:rbac:groups=example.your.domain,resources=tenantresources,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=example.your.domain,resources=tenantresources/status,verbs=get;update;patch

func (r *TenantAwareReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    logger := log.FromContext(ctx)

    // 1. 获取资源实例
    var resource examplev1.TenantResource
    if err := r.Get(ctx, req.NamespacedName, &resource); err != nil {
        if errors.IsNotFound(err) {
            // 资源已删除，无需处理
            return ctrl.Result{}, nil
        }
        logger.Error(err, "unable to fetch resource")
        return ctrl.Result{}, err
    }

    // 2. 租户隔离校验：确保当前 Reconciler 有权处理该租户
    if resource.Spec.TenantID == "" {
        logger.Info("resource missing tenantID, skipping")
        return ctrl.Result{}, nil
    }

    // 3. 幂等业务逻辑：从当前状态向期望状态收敛
    // 例如：确保 Deployment 副本数与 Spec 一致
    desiredReplicas := resource.Spec.Replicas
    // ... 实际状态对比与调整 ...

    // 4. 更新状态（使用乐观锁）
    resource.Status.CurrentReplicas = desiredReplicas
    if err := r.Status().Update(ctx, &resource); err != nil {
        logger.Error(err, "failed to update status")
        return ctrl.Result{}, err
    }

    logger.Info("reconcile completed", "tenantID", resource.Spec.TenantID)
    return ctrl.Result{}, nil
}

// SetupWithManager 注册 Controller
func (r *TenantAwareReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&examplev1.TenantResource{}).
        WithEventFilter(predicate.GenerationChangedPredicate{}). // 仅处理 spec 变更
        Complete(r)
}

常见陷阱：

忽略删除事件： 未处理 IsNotFound 会导致 Reconcile 循环卡在错误重试中。
非幂等更新： 每次 Reconcile 都执行 Update 而不检查实际状态，会触发无限循环。
租户上下文丢失： 在 Reconcile 方法内未校验 TenantID，导致跨租户资源操作。

2.5 Controller-Runtime 组件协作关系

下图展示了 Manager、Controller、Reconciler 与 Informer 之间的协作关系：

2.6 本章小结

项目结构： api/ 定义资源模型，controllers/ 实现 Reconcile 循环，config/ 管理部署与 RBAC。
Reconcile 循环： 必须保证幂等性，使用乐观锁更新状态，合理设置重试策略。
核心接口： Manager 管理生命周期，Controller 负责事件调度，Reconciler 执行业务逻辑，Source 提供事件源。
多租户切入点： 在 Reconciler 中校验 TenantID，在 Manager 中注入租户隔离的 Cache 与 Client。