4. 控制器核心逻辑：Reconcile 函数详解、Request 对象、Result 对象、Requeue 机制

Reconcile 函数是 Operator 控制器的“心脏”。每当集群状态与期望状态出现偏差时，控制器框架就会调用这个函数，驱动系统向期望状态收敛。理解 Reconcile 的输入、输出与重试机制，是调试控制器行为的基础。

4.1 Reconcile 函数签名与调用时机

在 kubebuilder 或 operator-sdk 生成的脚手架中，Reconcile 函数通常位于 controllers/xxx_controller.go 中，其标准签名如下：

func (r *MyReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

控制器运行时（controller-runtime）会在以下事件发生时自动将 Request 入队并触发 Reconcile：

4.2 Request 对象：事件的身份标识

ctrl.Request 结构体非常轻量，只包含两个字段：

type Request struct {
    types.NamespacedName
}

// types.NamespacedName 定义
type NamespacedName struct {
    Namespace string
    Name      string
}

它不携带事件的具体类型（创建/更新/删除），也不包含变更前后的对象内容。Reconcile 函数必须通过 r.Get(ctx, req.NamespacedName, &instance) 重新从 API Server 拉取最新状态。

4.3 Result 对象：告诉控制器下一步做什么

ctrl.Result 是 Reconcile 函数的返回值，控制着控制器是否立即重试、延迟重试或停止协调：

type Result struct {
    Requeue      bool
    RequeueAfter time.Duration
}

// 典型返回模式示例
// 1. 成功完成
return ctrl.Result{}, nil

// 2. 资源不存在，无需重试
return ctrl.Result{}, nil

// 3. 暂时失败，10秒后重试
return ctrl.Result{RequeueAfter: 10 * time.Second}, nil

// 4. 立即重试（慎用，容易造成热循环）
return ctrl.Result{Requeue: true}, nil

// 5. 不可恢复错误，记录并停止重试
return ctrl.Result{}, fmt.Errorf("fatal error: %w", err)

4.4 Requeue 机制：重试队列与退避策略

控制器运行时内部维护了一个工作队列（work queue），基于 Go 的 client-go/util/workqueue 实现。Requeue 的本质是将 Request 重新放入这个队列。

4.4.1 指数退避策略

当 Reconcile 返回 error 时，框架不会立即重试，而是采用指数退避：

• 基础延迟： 5 毫秒
• 最大延迟： 约 16 分钟（由 baseDelay 和 maxDelay 控制）
• 退避因子： 每次重试延迟翻倍，并加入随机抖动
• 重置条件： 成功处理（返回 nil error）后，退避计数器清零

// 退避延迟序列示例（近似值）
第1次失败: 5ms
第2次失败: 10ms
第3次失败: 20ms
第4次失败: 40ms
...
第12次失败: ~10s
第16次失败: ~2.5min
第20次失败: ~16min (达到上限)

4.4.2 Requeue 与退避的交互

理解以下关键规则，有助于调试“为什么 Reconcile 没有被调用”或“为什么调用过于频繁”：

4.5 Reconcile 完整生命周期 SVG 流程

下图展示了从事件触发到 Reconcile 返回的完整链路，以及 Requeue 机制在其中的位置：

4.6 调试 Reconcile 的常用手段

1. 日志注入： 在 Reconcile 开头打印 req.NamespacedName，在关键操作前后打印状态。
2. 事件记录： 使用 r.Recorder.Event(instance, corev1.EventTypeNormal, "Reconciled", "Success") 在资源对象上留下事件。
3. 指标暴露： 自定义 Prometheus 计数器，记录 Reconcile 调用次数、失败次数、处理耗时。
4. 单步调试： 使用 delve 附加到管理器进程，在 Reconcile 入口设置断点。
5. Requeue 监控： 通过 workqueue_depth 和 workqueue_retries 指标判断队列积压情况。