2. Kubernetes Operator 基础：Operator 模式、CRD 与 Controller、Reconcile 循环原理

在深入 Operator SDK 单元测试框架之前，必须透彻理解 Operator 的核心运行机制。本章从 Operator 模式的设计哲学出发，逐步拆解 CRD（自定义资源定义）、Controller（控制器）与 Reconcile（调谐）循环三者之间的协作关系，为后续编写可测试的控制平面代码奠定理论基础。

2.1 Operator 模式：声明式运维的终极实现

Operator 是 Kubernetes 上的一种应用打包、部署和管理模式，其本质是将人类运维知识编码为软件，通过 Kubernetes 原生机制自动执行。与传统的配置管理工具（如 Ansible、Puppet）不同，Operator 完全基于 Kubernetes 的声明式 API 体系工作。

对比维度 传统运维脚本 Kubernetes Operator
驱动方式 命令式（执行步骤） 声明式（描述期望状态）
状态管理 外部数据库或文件 Kubernetes API 对象（etcd）
故障恢复 需手动重试或外部监控 自动调谐循环，持续收敛
扩展性 依赖脚本编排 通过 CRD 定义任意领域对象
版本管理 无原生版本控制 CRD 多版本转换与存储

Operator 模式的核心价值在于：将领域专家的操作经验转化为可重复、可审计、可测试的代码。例如，一个数据库 Operator 知道如何创建集群、处理主从切换、执行备份恢复，这些知识被固化在 Controller 的 Reconcile 逻辑中。

关键认知： Operator 不是简单的“Kubernetes 上的脚本”，而是一个有状态、自循环、事件驱动的控制回路。它通过监听资源变化，持续将实际状态向用户定义的期望状态收敛。

2.2 CRD 与 Controller：Operator 的两大支柱

Operator 由两个核心组件构成：CRD（Custom Resource Definition） 定义数据模型，Controller 实现业务逻辑。二者通过 Kubernetes API Server 进行交互。

2.2.1 CRD：扩展 Kubernetes API 的数据模型

CRD 允许用户在 Kubernetes 中定义新的资源类型，就像内置的 Pod、Service 一样。Operator SDK 使用 types.go 文件定义 CRD 的结构体，并通过代码生成工具自动生成 CRD YAML 清单。

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
type MyApp struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   MyAppSpec   `json:"spec,omitempty"`
    Status MyAppStatus `json:"status,omitempty"`
}

type MyAppSpec struct {
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=10
    Replicas int32 `json:"replicas"`
    Image    string `json:"image"`
}

type MyAppStatus struct {
    AvailableReplicas int32  `json:"availableReplicas"`
    Phase             string `json:"phase"`
}

CRD 的关键字段包括：

  • Spec：用户输入的期望状态，由用户创建或更新资源时提供。
  • Status：Controller 回写的实际状态，反映当前集群中的真实情况。
  • Subresource：/status 子资源允许 Controller 独立更新状态，避免与用户写入 Spec 产生冲突。

2.2.2 Controller：事件驱动的业务执行者

Controller 是一个持续运行的循环，它通过 Informer 机制监听 CRD 实例的变化（创建、更新、删除），并将变化事件放入工作队列。Controller 从队列中取出事件后，调用 Reconcile 函数处理。

设计原则： Controller 不应直接操作 CRD 实例，而应通过 Reconcile 函数返回结果（是否需要重试、是否完成）来驱动下一步动作。这种解耦使得单元测试时可以轻松模拟事件源。

2.3 Reconcile 循环原理：从事件到收敛

Reconcile 循环是 Operator 的心脏。它接收一个 Request（包含命名空间和名称），然后执行以下步骤：

  1. 获取资源：从 API Server 读取当前 CRD 实例。
  2. 获取关联资源：读取该 CRD 实例所管理的子资源（如 Deployment、Service）。
  3. 对比状态：比较期望状态（Spec）与实际状态（Status + 子资源）。
  4. 执行操作：创建、更新或删除子资源，使实际状态向期望状态收敛。
  5. 更新状态：将最新的实际状态写回 CRD 的 Status 字段。
  6. 返回结果：返回 ctrl.Result 和 error，决定是否重新入队。
func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 1. 获取 MyApp 实例
    var myApp myappv1.MyApp
    if err := r.Get(ctx, req.NamespacedName, &myApp); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // 2. 获取当前 Deployment
    var deploy appsv1.Deployment
    err := r.Get(ctx, types.NamespacedName{
        Name:      myApp.Name,
        Namespace: myApp.Namespace,
    }, &deploy)

    // 3. 对比期望副本数与实际副本数
    if err != nil && apierrors.IsNotFound(err) {
        // 创建 Deployment
        deploy = *buildDeployment(&myApp)
        if err := r.Create(ctx, &deploy); err != nil {
            return ctrl.Result{}, err
        }
    } else if *deploy.Spec.Replicas != myApp.Spec.Replicas {
        // 更新副本数
        deploy.Spec.Replicas = &myApp.Spec.Replicas
        if err := r.Update(ctx, &deploy); err != nil {
            return ctrl.Result{}, err
        }
    }

    // 4. 更新状态
    myApp.Status.AvailableReplicas = deploy.Status.AvailableReplicas
    if err := r.Status().Update(ctx, &myApp); err != nil {
        return ctrl.Result{}, err
    }

    return ctrl.Result{}, nil
}
常见陷阱： Reconcile 函数必须是幂等的。同一 Request 被多次调用不应产生副作用。例如，创建 Deployment 前必须检查是否已存在，否则每次 Reconcile 都会重复创建。

2.4 Reconcile 循环的完整数据流

下图展示了从用户提交 CR 到 Operator 完成调谐的完整数据流，包含事件触发、队列调度、状态回写三个关键阶段。

Reconcile 循环完整数据流 用户 / kubectl API Server etcd Informer 工作队列 Reconcile 子资源 创建/更新 CR 持久化 Watch 入队 出队 创建/更新 状态回写 重新入队 说明：虚线箭头表示 Reconcile 返回 RequeueAfter 时的重新入队路径；实线箭头为正常数据流。

2.5 Reconcile 返回结果详解

Reconcile 函数的返回值 ctrl.Result 控制着调谐循环的下一次触发时机。正确理解这些返回值是编写高效 Operator 的关键。

Result 字段 取值 行为 典型场景
Requeue false 不重新入队，调谐结束 调谐成功，无需再次检查
Requeue true 立即重新入队 临时错误（如网络抖动），需要重试
RequeueAfter Duration 延迟指定时间后重新入队 轮询外部系统状态（如证书即将过期）
error 非 nil 自动重新入队（带指数退避） 严重错误（如 API Server 不可达）
测试要点： 单元测试中需要覆盖所有四种返回路径。Operator SDK 提供的 fakeclient 可以精确模拟 API Server 的返回错误，验证 Reconcile 在错误场景下的重试行为是否符合预期。

2.6 Operator 项目结构速览

使用 Operator SDK 初始化的项目具有标准目录结构，理解每个目录的职责有助于后续编写单元测试。

my-operator/
├── api/                  # CRD 类型定义
│   └── v1/
│       ├── myapp_types.go
│       └── groupversion_info.go
├── controllers/          # Controller 与 Reconcile 逻辑
│   ├── myapp_controller.go
│   └── suite_test.go     # 集成测试入口
├── config/               # Kubernetes 资源清单
│   ├── crd/              # CRD YAML
│   ├── rbac/             # RBAC 权限
│   └── samples/          # 示例 CR
├── internal/             # 内部工具包（可选）
├── main.go               # 入口
├── go.mod
└── Makefile

在后续章节中，我们将重点围绕 controllers/ 和 api/ 目录构建单元测试框架。controllers/suite_test.go 是 Operator SDK 默认生成的集成测试入口，而单元测试将直接针对 Reconcile 方法进行，不依赖真实的 Kubernetes 集群。

本章小结： Operator 模式通过 CRD 扩展 Kubernetes API，Controller 监听 CRD 变化并触发 Reconcile 循环。Reconcile 函数是幂等的状态收敛器，其返回值控制调谐频率。理解这三者的关系是编写可测试 Operator 代码的前提。下一章将深入 Operator SDK 的项目初始化与代码生成工具链。
← 上一章 📖 返回目录 下一章 →