4. Controller 核心逻辑：Reconcile 函数结构、事件触发机制、状态更新策略

Operator 的核心是 Controller，而 Controller 的灵魂是 Reconcile 循环。本章深入剖析 Reconcile 函数的骨架设计、事件如何驱动调谐、以及状态如何在集群与内存之间同步。理解这三部分，就等于掌握了 Operator 的“大脑”与“神经”。

4.1 Reconcile 函数结构：调谐循环的骨架

每个 Controller 都包含一个 Reconcile 方法，它接收 Request（命名空间/名称），返回 Result 和 error。标准结构分为三个阶段：读取当前状态 → 对比期望状态 → 执行调和动作。

func (r *MyReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 1. 获取自定义资源实例
    myResource := &myv1.MyResource{}
    if err := r.Get(ctx, req.NamespacedName, myResource); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // 2. 获取当前集群状态（Deployment、Service 等）
    currentDeploy := &appsv1.Deployment{}
    err := r.Get(ctx, types.NamespacedName{Name: myResource.Name, Namespace: myResource.Namespace}, currentDeploy)
    if err != nil && !apierrors.IsNotFound(err) {
        return ctrl.Result{}, err
    }

    // 3. 对比期望状态与当前状态，执行创建/更新/删除
    desiredDeploy := buildDesiredDeployment(myResource)
    if apierrors.IsNotFound(err) {
        // 不存在则创建
        if err := r.Create(ctx, desiredDeploy); err != nil {
            return ctrl.Result{}, err
        }
    } else {
        // 存在则更新
        if err := r.Update(ctx, desiredDeploy); err != nil {
            return ctrl.Result{}, err
        }
    }

    // 4. 更新自定义资源状态
    myResource.Status.Phase = "Ready"
    myResource.Status.ObservedGeneration = myResource.Generation
    if err := r.Status().Update(ctx, myResource); err != nil {
        return ctrl.Result{}, err
    }

    // 5. 返回结果：RequeueAfter 用于周期性重试
    return ctrl.Result{RequeueAfter: 30 * time.Second}, nil
}

4.2 事件触发机制：谁唤醒了 Reconcile？

Controller 不会主动轮询，而是通过 事件源（Event Source） 和 处理器（Handler） 将集群变化转化为 Reconcile Request 入队。下图展示了从资源变更到 Reconcile 调用的完整链路。

4.3 状态更新策略：从 Spec 到 Status 的闭环

Operator 的最终输出是更新自定义资源的 Status 字段。状态更新必须遵循以下策略，才能保证集群控制器与外部系统的一致性。

4.4 状态更新代码模式：条件与阶段

以下代码展示了如何在 Reconcile 末尾安全地更新状态，并利用 meta.SetStatusCondition 管理条件列表。

import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/api/meta"
)

// 在 Reconcile 末尾更新状态
func (r *MyReconciler) updateStatus(ctx context.Context, cr *myv1.MyResource, phase string, err error) error {
    // 只在状态变化时更新
    if cr.Status.Phase == phase {
        return nil
    }

    cr.Status.Phase = phase
    cr.Status.ObservedGeneration = cr.Generation

    // 设置条件
    condition := metav1.Condition{
        Type:               "Ready",
        Status:             metav1.ConditionTrue,
        LastTransitionTime: metav1.Now(),
        Reason:             "ReconcileSuccess",
        Message:            "Resource reconciled successfully",
    }
    if err != nil {
        condition.Status = metav1.ConditionFalse
        condition.Reason = "ReconcileError"
        condition.Message = err.Error()
    }
    meta.SetStatusCondition(&cr.Status.Conditions, condition)

    return r.Status().Update(ctx, cr)
}

4.5 事件触发与状态更新的协同流程

下面这张图展示了从事件入队到状态更新的完整闭环，帮助理解 Controller 的“感知-决策-执行-反馈”循环。

4.6 总结：Reconcile 核心设计要点

• 幂等性：Reconcile 函数无论执行多少次，结果一致。
• 事件驱动：通过 EventHandler 将资源变更转为队列任务，避免轮询。
• 限速与去重：WorkQueue 内置限速和去重机制，防止并发风暴。
• 状态闭环：更新 Status 后可能触发新事件，通过 ObservedGeneration 防止无限循环。
• 乐观锁：Status 更新使用 resourceVersion 冲突检测，失败后重试。