标签： Finalizer

在 controller-runtime (基于 v0.15.0) 的 Operator 开发中，最隐蔽的 OOM 与性能杀手往往源于开发者在 Reconcile 循环中滥用全局 client.List 进行内存级过滤，而非向 Manager 注册 FieldIndexer。这种反模式会强制 Informer 监听并缓存集群全量资源，直接撑爆本地 ThreadSafeStore。当 Operator 因 OOM 陷入 CrashLoopBackOff 时，又会产生连锁反应：拦截了删除事件的 Finalizer 无法执行清理逻辑，导致海量 CR（Custom Resource）和关联 Namespace 陷入永久 Terminating 死锁。解决此问题的核心在于：利用 FieldIndexer 下推查询条件到索引层，并严格遵循安全的 Finalizer 状态机编排。

故障现场：Operator 频繁 OOM 与僵尸 CR 风暴

排查某次生产环境问题时，监控系统发出严重告警：

1. Operator Pod OOMKilled：内存使用量频繁突破 2Gi 的 Limit 阈值。

2. Reconcile 延迟剧增：P99 Reconcile 时延从毫秒级劣化至 15 秒以上。

3. 僵尸对象堆积：大量自定义资源 DataJob 及其所在的 Namespace 处于 Terminating 状态无法回收，集群 API Server 的 Watch 流连接数激增。

拉取 Operator 的 Go pprof heap dump 进行现场剖析：

go tool pprof -top http://operator-svc:8081/debug/pprof/heap

输出结果极为刺眼，超过 85% 的内存消耗集中在 k8s.io/client-go/tools/cache.(*threadSafeMap).Update 和 k8s.io/apimachinery/pkg/apis/meta/v1/unstructured。这说明本地 Informer Cache 中囤积了极其庞大的对象数据。

审查业务侧代码，在 DataJob 的 Reconcile 主逻辑中发现了这坨致命的“全表扫描”代码：

// 致命的反模式代码
podList := &corev1.PodList{}
// 直接 List 全局 Pod，未指定 Namespace 或 Label/Field Selector
if err := r.Client.List(ctx, podList); err != nil {
    return ctrl.Result{}, err
}

var ownedPods []corev1.Pod
for _, pod := range podList.Items {
    // 在内存中暴力遍历过滤 owner
    for _, owner := range pod.OwnerReferences {
        if owner.Name == dataJob.Name {
            ownedPods = append(ownedPods, pod)
        }
    }
}

为什么滥用 client.List 会导致 Informer Cache 撑爆？

在回答这个问题之前，必须理解 controller-runtime 的读写分离哲学与 Informer 底层运行机制。

默认情况下，mgr.GetClient() 注入给 Reconciler 的 Client 是一个 Split Client（读写分离客户端）。

• 写操作（Create/Update/Delete/Patch）：直接透传给 APIServer。

• 读操作（Get/List）：默认全部被拦截并路由到本地 Informer Cache（CacheReader）。

当你调用 r.Client.List(ctx, podList) 时，底层发生了什么？

1. controller-runtime 发现你要 List Pod 资源。

2. 如果此前没有针对 Pod 初始化过 Informer，Manager 会动态启动一个全量 Pod Informer。

3. 该 Informer 通过 Reflector 向 APIServer 发起 ListAndWatch 请求。

4. APIServer 将集群中所有的 Pod（假设有 50,000 个）推送到本地。

5. DeltaFIFO 接收数据，经过处理后全量灌入 ThreadSafeStore（基于 Go map 实现的内存缓存）。

灾难的根源：虽然缓存避免了频繁请求 APIServer，但 Pod 是一个极其臃肿的结构体（包含大段的 Annotations、Env、Volume 挂载信息）。50,000 个 Pod 在 Go 内存中反序列化后，轻易就能吃掉 1GB~2GB 内存。为了过滤区区几个属于特定 CR 的 Pod，把全集群的 Pod 搬进内存，典型的“为了吃一小口肉，把整个养猪场买下来”。

实战解法：注入 FieldIndexer 下推索引

要消除这种全表扫描引发的 OOM，必须利用 FieldIndexer。它的原理是在 Informer 同步数据到 ThreadSafeStore 时，根据你定义的提取函数，提前构建好倒排索引。

1. 注册索引 (SetupWithManager)

在 Operator 启动时，将 metadata.ownerReferences 注册为可检索的字段索引：

const jobOwnerKey = ".metadata.controller"

func (r *DataJobReconciler) SetupWithManager(mgr ctrl.Manager) error {
    // 建立基于 OwnerReference 的倒排索引
    if err := mgr.GetFieldIndexer().IndexField(context.Background(), &corev1.Pod{}, jobOwnerKey, func(rawObj client.Object) []string {
        pod := rawObj.(*corev1.Pod)
        owner := metav1.GetControllerOf(pod)
        if owner == nil {
            return nil
        }
        // 确保 Owner 是当前 GVK
        if owner.APIVersion == apiGVStr && owner.Kind == "DataJob" {
            return []string{owner.Name}
        }
        return nil
    }); err != nil {
        return err
    }

    return ctrl.NewControllerManagedBy(mgr).
        For(&batchv1.DataJob{}).
        Owns(&corev1.Pod{}).
        Complete(r)
}

2. 重构 Reconcile 逻辑

将内存遍历替换为按字段匹配（client.MatchingFields）：

podList := &corev1.PodList{}
// 此时只会从 Cache 的索引桶中精准捞取对应 name 的对象
err := r.List(ctx, podList, client.InNamespace(req.Namespace), client.MatchingFields{jobOwnerKey: dataJob.Name})
if err != nil {
    return ctrl.Result{}, err
}

通过这种方式，Informer 依然会在后台维护缓存，但由于限定了 Namespace（通过 RBAC 和 Manager 启动参数 Cache 限制监听范围），以及规避了无效的大切片拷贝操作，Operator 的内存消耗被严格压制在百兆级别。

打破 Finalizer 级联死锁

回到故障现场的第三个问题：为什么大量资源卡在 Terminating？ 原因在于 Operator 由于上述 OOM 问题不断 Crash，导致资源删除事件无法被正常消费。而这些 CR 注入了 Finalizer。

在 K8S 中，只要对象的 metadata.finalizers 列表不为空，APIServer 就只会将对象的 DeletionTimestamp 赋值，而不会真正从 Etcd 中物理删除该记录。若 Operator 宕机，Finalizer 迟迟不被移除，资源就会僵死。

防御性 Finalizer 编排范式

处理 Finalizer 必须极其谨慎，严禁在网络抖动或外部 API 调用失败时强行移除 Finalizer，否则会导致依赖的云端或集群外部资源泄露。标准的安全状态机如下：

const dataJobFinalizer = "batch.example.com/finalizer"

func (r *DataJobReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    dataJob := &batchv1.DataJob{}
    if err := r.Get(ctx, req.NamespacedName, dataJob); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // 检查资源是否正在被删除
    if dataJob.ObjectMeta.DeletionTimestamp.IsZero() {
        // 未被删除，检查是否需要注入 Finalizer
        if !controllerutil.ContainsFinalizer(dataJob, dataJobFinalizer) {
            controllerutil.AddFinalizer(dataJob, dataJobFinalizer)
            if err := r.Update(ctx, dataJob); err != nil {
                return ctrl.Result{}, err
            }
        }
    } else {
        // 资源处于 Terminating 状态，执行清理逻辑
        if controllerutil.ContainsFinalizer(dataJob, dataJobFinalizer) {
            // 1. 执行自定义清理逻辑 (必须幂等，并处理超时/失败)
            if err := r.cleanUpExternalResources(dataJob); err != nil {
                // 清理失败，返回 err 触发重试，绝对不能移除 Finalizer
                return ctrl.Result{}, err
            }

            // 2. 清理成功，安全移除 Finalizer
            controllerutil.RemoveFinalizer(dataJob, dataJobFinalizer)
            if err := r.Update(ctx, dataJob); err != nil {
                return ctrl.Result{}, err
            }
        }
        // 允许终止 Reconcile
        return ctrl.Result{}, nil
    }

    // 正常的业务 Reconcile 逻辑...
    return ctrl.Result{}, nil
}

避坑指南：在 Update Finalizer 状态时，极易遭遇 Conflict (HTTP 409) 错误。这是因为在处理清理逻辑的几秒钟内，对象的 ResourceVersion 可能已经被其他 Controller 改变。controller-runtime 会自动在下一个 Reconcile 循环重试，因此你的 cleanUpExternalResources 必须是严格幂等的。

常见问题 (Q&A)

Q1：什么时候应该绕过 Informer Cache 直接读取 APIServer？ 极少数情况。当你需要强一致性读取（例如处理极度敏感的锁机制或鉴权），不能容忍毫秒级的 Cache 同步延迟时。在 controller-runtime 中，可以通过注入 client.Reader 并使用 client.NewAPIReader(mgr.GetClient()) 获取直连 APIServer 的对象。但严禁在频繁的 Reconcile 循环中对全量列表使用直读，否则立刻引发 APIServer QPS 告警。

Q2：如果我只需要获取资源的 metadata，不想缓存庞大的 spec/status 怎么办？ 在较新的 controller-runtime 中（配合 Kubernetes 1.27+），你可以启用 MetadataOnly Client。它基于 APIServer 的 PartialObjectMetadata API，Informer 在本地仅缓存对象的 ObjectMeta 结构体，这能将数百 MB 的 Cache OOM 风险直接降维到几 MB。

Q3：为什么我加上了 FieldIndexer，Operator 启动时还是对 APIServer 造成了 Watch 风暴？ 检查你启动 Manager 时的 Options.Cache 配置。默认行为是全局监控（Watch All Namespaces）。如果你是一个 Namespace-scoped 的 Operator，务必在 Cache 配置中指定 DefaultNamespaces 列表。否则，每个 GVK 的 Informer 启动时依然会触发集群全量 Resync。