标签： OOM排查

结论先行：在基于 controller-runtime (如 v0.15.0) 开发 Operator 时，若未对 CRD 开启 /status 子资源隔离，且缺失基于 GenerationChangedPredicate 的事件过滤，每次状态回写都会引发 ResourceVersion 变更，进而被 Informer 重新推入 Workqueue，形成无限 Reconcile 死循环。这会瞬间打爆 API Server 的 QPS，并导致 Controller 因 DeltaFIFO 积压而 OOM。核心解法：强制开启 Status Subresource，应用 Generation 过滤机制，并在逻辑闭环中严格校验 ObservedGeneration。

案发现场：API Server 限流与 Controller OOM

某次线上巡检排查过程中，监控大盘突然亮起红灯：K8s 集群 (v1.28.2) 的 API Server 出现大量 HTTP 429 (Too Many Requests) 限流报错。 排查发现，某个自研的 Operator 所在的 Pod 内存持续飙升，触发了 OOMKilled，且在 CrashLoopBackOff 期间，集群的 Load Average 显著下降，一旦重启立马复现。

拉取 Operator 的 Prometheus Metrics 暴露端点，抓取到的关键指标如下：

• workqueue_adds_total{name="mycrd-controller"} 每秒暴增 5000+。

• workqueue_depth 长期维持在 10 万以上的极高水位。

• controller_runtime_reconcile_total 速率呈指数级上升。

这显然是一个典型的“死循环”特征。提取 OOM 前的 pprof heap 快照分析，内存几乎全量消耗在 k8s.io/client-go/tools/cache.(*DeltaFIFO).Queue 中。换句话说，Informer 的底层事件队列被彻底塞满了。

查看该 Operator 对应控制器的核心代码片段：

func (r *MyCRDReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var instance myv1.MyCRD
    if err := r.Get(ctx, req.NamespacedName, &instance); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // 核心业务逻辑：比如创建底层的 Deployment 或执行一些远程 API 调用
    err := r.DoSomeHeavyLogic(ctx, &instance)
    if err != nil {
        return ctrl.Result{}, err
    }

    // 更新状态
    instance.Status.Phase = "Running"
    instance.Status.Message = "Reconcile successful"
    // 致命缺陷点
    if err := r.Client.Update(ctx, &instance); err != nil {
        return ctrl.Result{}, err
    }

    return ctrl.Result{}, nil
}

为什么一次简单的 Status 更新会引发全局雪崩？

要理解这个死循环的根源，必须剖析 K8s 内部的资源版本控制与 Informer Watch 机制。

在 Kubernetes 中，所有的资源对象都有两个关键的元数据字段：

1. metadata.generation：由 API Server 维护。只有当资源的 Spec 发生变化时，该值才会递增。

2. metadata.resourceVersion：K8s 底层 Etcd MVCC 机制的映射。任何对该资源的修改（包括加 Label、改 Annotation、更新 Status），都会导致 resourceVersion 改变。

在上述出问题的代码逻辑中，发生了如下的“死亡飞轮”：

1. 用户创建 CRD (Generation = 1, ResourceVersion = 100)。

2. Informer 监听到创建事件，推入 Workqueue。

3. Controller 触发 Reconcile，执行业务逻辑。

4. Controller 修改 CRD 状态，并调用 r.Client.Update 回写到 API Server。

5. API Server 接受更新，因为没有分离 /status 子资源，这是对整个对象的全量更新，ResourceVersion 变为 101。

6. 灾难发生：Informer 的 Reflector 通过 Watch 机制感知到了 ResourceVersion 从 100 变到了 101，认为对象发生了变化（UpdateEvent），将其重新包装并扔进 DeltaFIFO。

7. Controller 再次拿到该对象的请求，重新触发 Reconcile。

8. 再次覆盖 Status，ResourceVersion 变为 102，再次触发 Watch…

由于 DoSomeHeavyLogic 包含耗时操作，高频的 Update 直接让队列积压，内存爆炸。同时，API Server 在短时间内承受了海量的无效写请求，导致全局延迟抖动。

架构级重构与防御性加固

解决此类问题不能仅靠打补丁，需要遵循 Operator 开发的防御性最佳实践进行系统性修复。

1. 强制启用 Status Subresource

K8s 提供了 Subresource 机制，将业务期望（Spec）与实际状态（Status）在 API 层面隔离。 在 CRD 的 Go 结构体上方，必须声明 kubebuilder 注解：

//+kubebuilder:object:root=true
//+kubebuilder:subresource:status
//+kubebuilder:printcolumn:name="Phase",type="string",JSONPath=".status.phase"
//+kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"

type MyCRD struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   MyCRDSpec   `json:"spec,omitempty"`
    Status MyCRDStatus `json:"status,omitempty"`
}

重新执行 make manifests，这会在生成的 CRD YAML 中添加 status 子资源。 在 Reconcile 代码中，必须使用专用的 Status 客户端：

// 错误写法：会全量覆盖，极易产生并发冲突
// r.Client.Update(ctx, &instance)

// 正确写法：仅更新 Status 子资源
if err := r.Status().Update(ctx, &instance); err != nil {
    return ctrl.Result{}, err
}

2. 注入 GenerationChangedPredicate 拦截器

虽然启用了 Status Subresource，但其他 Controller 或人工修改 Label/Annotation 依然会改变 ResourceVersion 触发 Reconcile。如果业务逻辑无需关心元数据变更，应当在 Controller 注册时进行拦截。

controller-runtime 提供了强大的 Event Filters (Predicates)：

import "sigs.k8s.io/controller-runtime/pkg/predicate"

func (r *MyCRDReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&myv1.MyCRD{}, builder.WithPredicates(predicate.GenerationChangedPredicate{})).
        Complete(r)
}

深挖一下 GenerationChangedPredicate 的源码逻辑： 它在处理 UpdateEvent 时，严格对比旧对象和新对象的 Generation。

// 源码片段摘录 k8s.io/controller-runtime/pkg/predicate/predicate.go
func (GenerationChangedPredicate) Update(e event.UpdateEvent) bool {
    if e.ObjectOld == nil || e.ObjectNew == nil {
        return false
    }
    // 只有当 Spec 发生实质性改变时，才允许进入 Workqueue
    return e.ObjectNew.GetGeneration() != e.ObjectOld.GetGeneration()
}

3. 实现 ObservedGeneration 闭环校验

作为高可用的极致追求，Status 设计中应当包含 ObservedGeneration 字段。这能让观察者（包括人类和上层系统）一眼判断出当前 Status 是否已经反映了最新的 Spec。

type MyCRDStatus struct {
    Phase              string `json:"phase,omitempty"`
    ObservedGeneration int64  `json:"observedGeneration,omitempty"` // 记录已处理完毕的 Generation
}

Reconcile 中的闭环处理逻辑：

func (r *MyCRDReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 1. 获取对象...

    // 2. 防御性判断：如果当前 Status 已经处理过当前的 Spec，直接 Return
    if instance.Status.ObservedGeneration == instance.Generation {
        // 说明没有新的业务需要处理
        return ctrl.Result{}, nil
    }

    // 3. 核心业务逻辑执行...

    // 4. 更新状态与 Generation 快照
    instance.Status.Phase = "Running"
    instance.Status.ObservedGeneration = instance.Generation // 推进位点
    if err := r.Status().Update(ctx, &instance); err != nil {
        return ctrl.Result{}, err
    }

    return ctrl.Result{}, nil
}

这种设计是标准的水平触发（Level-Triggered）机制的体现：我们只关心期望状态（Generation）与实际状态（ObservedGeneration）是否一致，一切流转都以此为依据。

常见问题 (FAQ)

Q1: 使用了 GenerationChangedPredicate 后，为什么 CRD 实例删除时，配置好的 Finalizer 没有被触发？ 在使用 GenerationChangedPredicate 时，开发者经常误以为它会拦截 Delete 事件。实际上查看源码可知，它默认是放行 DeleteEvent 的。如果 Finalizer 卡住，通常是因为在 Reconcile 入口处使用了 client.IgnoreNotFound(err) 吞掉了错误，或者在拦截器配置中手写了覆盖逻辑（如自定义的 Predicate 组合丢失了 Delete 接口的实现）。删除动作不会改变 Generation，但会设置 DeletionTimestamp，必须确保这部分逻辑不被过滤。

Q2: Reconcile 里面高频调用 r.Get() 会不会压垮 API Server？ 不会。controller-runtime 默认注入的 Client 是一个 SplitClient。它的 Get 和 List 操作默认命中 Informer 在本地内存中维护的 Indexer 缓存，而非直接发起 HTTP 请求给 API Server。但需要注意：不要在缓存未 Ready 前调用，也不要对无权限 Watch 的资源（如 Secret 全局 List）滥用，否则会 fallback 回 API Server 或直接抛错。

Q3: 在更新 Status 时，Update 经常报 the object has been modified; please apply your changes to the latest version and try again，如何优雅解决？ 这是典型的乐观锁冲突（Conflict）。在并发极高或者 Informer 缓存延迟时，你拿到的 ResourceVersion 已经落后于 API Server 里的版本。 推荐的方案是弃用 Update，改用 Patch（优先使用 ServerSideApply 策略）。

patch := client.MergeFrom(instance.DeepCopy())
instance.Status.Phase = "Running"
err := r.Status().Patch(ctx, &instance, patch)

Patch 操作只需要提交增量修改，极大降低了由于 ResourceVersion 冲突导致的频繁重试率，从底层释放了队列压力。