kube-apiserver 缓存重建阶段如何安排控制器重试：从 429 到恢复可观测性

Kubernetes v1.37 里，watchcache 初始化期间看到 HTTP 429，不一定代表 API Server 坏了。更准确的解释是：缓存还没有准备好时，kube-apiserver 主动拒绝可能拖垮 etcd 或占满 API Priority and Fairness（APF）并发席位的请求，让客户端稍后重试。

关键边界只有一句话：普通 WATCH 和大多数 LIST 可能返回 429；不带 selector、同时带有 limit 的有界 LIST，才是官方 KEP 明确保留的 etcd 委托路径。

先判断 429 是保护动作还是 API Server 故障

watchcache 本质上是 API Server 内存中的对象缓存。启动或重初始化时，缓存需要从存储层建立状态；如果大量 watch 长时间挂起，它们会持续占用 APF 的 seat，甚至让同一优先级的读写请求都排不上队。v1.37 将剩余的初始化 PostStartHook 稳定化，目标就是让请求有秩序地失败，而不是堆积成洪峰。

因此先看三个信号：请求是否集中发生在 API Server 启动、升级或缓存重建之后；响应是否带有 Retry-After；/readyz 是否仍在恢复。若 429 随就绪恢复而下降，它更像保护动作；若就绪长期不恢复，才需要转向 API Server、etcd 或配置故障排查。

按 WATCH、GET、LIST 的请求形状判断分流

KEP-4568 给出的设计不是“所有请求一律 429”。GET 成本有界，可以委托给 etcd。LIST 则只先放行同时满足两个条件的请求：没有任何 selector，并且设置了 limit。前者保证读到的对象不会因为过滤而大量丢弃，后者限制单次读取规模。

可以把排障时的请求形状记成这张表：

图1：watchcache 未就绪时，按请求形状观察 WATCH、受限 LIST 与选择器 LIST 的分流结果。

让客户端以退避方式重试而不是放大洪峰

控制器或自定义客户端不要把 429 当成“立即再发一次”的普通业务错误。最小策略是读取 Retry-After，没有该值时采用带抖动的指数退避，并给重试次数和总等待时间设上限。以 curl 做人工验证时，也应模拟这种节奏：

curl -i --retry 5 --retry-delay 2 --retry-all-errors \
  "https://apiserver.example/api/v1/pods?limit=100"

生产控制器还要避免在 watch 失败后瞬间触发全量 LIST。应让 reflector 或等价客户端负责退避，再用较小的有界 LIST 重新建立游标。若业务确实需要 selector，优先缩小 namespace、标签范围或时间窗口，而不是删除保护条件。

用就绪、429 比例和请求形状验收恢复

恢复验收建议按“状态—指标—行为”三层做。状态层检查 kubectl get --raw='/readyz?verbose'；指标层观察 apiserver_request_total{code="429"} 是否回落，并按客户端身份定位异常重试者；行为层分别发起一次普通 watch、带 selector 的 list 和无 selector 且带 limit 的 list，确认客户端能等待并继续。

不要仅凭一次 200 就宣布恢复：watchcache 完成后，APF 仍可能因历史洪峰暂时排队。相反，也不要因短时 429 就关闭 ResilientWatchCacheInitialization。只有在就绪长期失败、429 持续异常升高且已确认客户端退避正确时，才进入版本与 API Server 配置级回滚评估。

图2：用就绪探针、429 指标和客户端退避三条证据链确认控制面恢复。

相关问题

为什么不把所有 LIST 都直接返回 429？

API Server 自己的 informer 也需要 LIST 完成初始化；全部拒绝会反过来拖慢恢复。所以保留无 selector 且带 limit 的有界路径。

429 会不会自动变成 410 Gone？

不会。429 表示当前请求被保护性拒绝；410 通常与客户端要求的 resourceVersion 已不可用有关，处理逻辑不同。

应该先调大 APF 并发吗？

不应把调大并发当第一反应。先确认请求形状和重试节奏，否则更大的容量可能只是把洪峰继续推向 etcd。

资料：Kubernetes v1.37 发布说明、KEP-4568、API Concepts。