API Server限流 – HDUO Lab

某次生产集群突发核心链路大面积超时，监控面板一片惨红。排查发现 Kube-APIServer 的 CPU 使用率直接打满，频繁触发 OOM 重启，周边控制面组件（Controller Manager、Scheduler）因无法与 API Server 通信陷入假死。抓取审计日志和指标后，最终结论令人哭笑不得：业务线研发在编写自定义 Operator 时，违背了 Kubernetes 的控制循环范式，在 Reconcile 逻辑中通过 client.Update() 直接修改 CR (Custom Resource) 的 Annotations 来记录同步状态，且未配置任何 EventFilter。这导致每一次更新都会触发 Informer 产生新的事件，形成死循环，硬生生把 API Server 当成高频 MQ 压垮。 修复方案很简单：在 CRD 启用 /status 子资源，代码中改用 client.Status().Update() 更新状态，并强制注入 GenerationChangedPredicate 过滤器。

案发现场：API Server 的“双十一”

接到告警的第一时间，我切到 Master 节点查看系统负载，Load Average 飙到了 120+，top 显示 kube-apiserver 进程 CPU 占用率接近 4000%（40核被吃干榨净）。

顺手敲一波 Prometheus 查询，查看 API Server 的 QPS：

sum(rate(apiserver_request_total{code=~"2.."}[1m])) by (verb, resource)

结果极其离谱：对某个自定义资源 datajobs.batch.company.com 的 UPDATE 请求 QPS 竟然高达 1.5 万！

再看对应 Operator Pod 的日志，屏幕在疯狂滚动同一个控制器的 Reconcile 日志，毫无阻塞，疯狂流转：

{"level":"info","ts":"...","logger":"controller.datajob","msg":"Reconciling DataJob","name":"job-test-01","namespace":"default"}
{"level":"info","ts":"...","logger":"controller.datajob","msg":"Successfully updated job sync time","name":"job-test-01"}

我拉取了该控制器的 Prometheus 指标：

rate(workqueue_adds_total{name="datajob"}[1m])

入队速率和 API Server 的 Update QPS 完美贴合。破案了，典型的无限 Reconcile 导致的雪崩。

扒开源码：教科书式的反模式

拿到业务线同学的源码，定位到 Reconcile 函数的最后几行，一段毫无防御性编程意识的代码赫然出现：

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

    // ... 核心业务逻辑执行 (比如调外部 API) ...

    // 致命错误开始：把状态写进 Annotations，并调用 Update
    if job.Annotations == nil {
        job.Annotations = make(map[string]string)
    }
    job.Annotations["lastSyncTime"] = time.Now().Format(time.RFC3339)
    job.Annotations["syncStatus"] = "Success"

    // 这里直接触发了灾难
    if err := r.Update(ctx, &job); err != nil {
        return ctrl.Result{}, err
    }

    return ctrl.Result{}, nil
}

为什么这会引发无限循环？我们过一遍 K8S Informer 的底层机制：

Watch 机制响应： 当你调用 r.Update(ctx, &job) 成功后，API Server 会将数据落盘 ETCD，并使该对象的 metadata.resourceVersion 递增。
Informer 捕获： Controller 的 Informer (底层是 Reflector) 通过 Watch 机制感知到了 resourceVersion 的变化，生成一个 Update 事件放入 DeltaFIFO 队列。
入队 WorkQueue： 事件经过 Controller 的 EventHandler，将该资源的 NamespacedName 再次推入 WorkQueue。
再次 Reconcile： 你的 Reconcile 函数被再次触发，执行业务逻辑，更新 lastSyncTime（时间变了），再次调用 r.Update()。
死循环闭环： resourceVersion 再次增加，Informer 再次捕获… 恭喜你，制造了一个没有延迟的永动机。

把 ETCD 当 Redis 刷，把 API Server 当千万级 MQ 压，这就是典型的面向搜索引擎编程、不深入理解 K8S 声明式 API 底层原理留下的祸根。

正规军的做法：Status Subresource 与 Predicate

在 Kubernetes 架构中，一个资源对象应该严格区分为 Spec（期望状态）和 Status（实际状态）。修改 Spec 属于用户的意图，修改 Status 属于控制器的反馈。为了避免反馈引发无意义的重试，K8S 提供了严密的机制，必须形成肌肉记忆。

1. 开启 `/status` 子资源

在 Kubebuilder 或 Operator SDK 中，必须为你的 CRD 增加 status 注解。这样 API Server 才会生成独立的 /status 路由。

//+kubebuilder:object:root=true
//+kubebuilder:subresource:status

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

    Spec   DataJobSpec   `json:"spec,omitempty"`
    Status DataJobStatus `json:"status,omitempty"`
}

2. 使用 Status().Update()

在代码中，严禁使用 r.Update() 来更新状态，必须使用 r.Status().Update()。

// 正确做法：更新 Status 字段
job.Status.LastSyncTime = metav1.Now()
job.Status.SyncStatus = "Success"

if err := r.Status().Update(ctx, &job); err != nil {
    return ctrl.Result{}, err
}

原理解析： API Server 对 /status 端点的请求做了特殊处理。当你更新 /status 时，对象的 metadata.generation 不会增加（只有更新 Spec 时才会增加）。但注意，此时 metadata.resourceVersion 依然会增加，这就需要下一步的配合。

3. 拦截无效事件：GenerationChangedPredicate

既然更新 Status 也会改变 resourceVersion，导致 Informer 收到事件，我们怎么切断循环？答案是在 Controller 绑定时，配置事件过滤器（Event Filter）。

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

func (r *DataJobReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&batchv1.DataJob{}, builder.WithPredicates(predicate.GenerationChangedPredicate{})).
        Complete(r)
}

GenerationChangedPredicate 的底层逻辑极为精妙：它会对比 Update 事件前后的 OldObject 和 NewObject。如果 OldObject.GetGeneration() == NewObject.GetGeneration()，则直接丢弃该事件，不入 WorkQueue。由于 Status().Update() 不改变 Generation，这个事件被成功拦截，死循环被完美阻断。

兜底防线：WorkQueue 的 RateLimiter

除了代码层面的规范，这次事故还暴露了一个问题：为什么单 Pod 的 Operator 能打出上万 QPS？因为 controller-runtime 默认的 RateLimiter 主要是针对出错重试（Requeue) 的指数退避。如果是 return ctrl.Result{}, nil 的正常流程被外部连续触发，它是不会限流的。在核心集群开发 Operator 时，建议对 Client 的 QPS 进行防御性限制：

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
    Scheme: scheme,
    // 限制 Client 与 APIServer 交互的吞吐
    // 默认 QPS 为 20，Burst 为 30，按需谨慎调整，不要盲目调大
})

同类问题排查清单（Operator 避坑指南）

API Server CPU 突增排查： 优先拉取 apiserver_request_total 指标，按照 verb 和 resource 进行 TopN 聚合，迅速定位是哪个 CRD 引起的风暴。
WorkQueue 积压监控： Operator 的 Prometheus 指标中，必须监控 workqueue_depth（队列深度）和 workqueue_adds_total（入队速率）。入队速率若呈陡峭直线，99% 是写了死循环。
Spec 与 Status 的边界校验： Review 代码时，全局搜索 client.Update()。只要其操作的对象包含了状态数据的回写（哪怕是写在 Annotations/Labels 里），立刻打回重构，强制改为 /status 子资源加 client.Status().Update()。
Predicate 过滤必加： 所有的 Controller 初始化阶段，除非有极其特殊的监听 Metadata 变更的需求，否则无脑加上 predicate.GenerationChangedPredicate{}，这是避免 Reconcile 雪崩最廉价且最有效的防火墙。

标签： API Server限流

深入 K8S Operator 雪崩排查：Update 滥用引发的无限 Reconcile 与 API Server 瘫痪实战