Kubernetes v1.37 watchcache 初始化为什么返回 429：控制面恢复时的请求洪峰边界

如果 kube-apiserver 重启或某类资源的 watchcache 正在重新初始化，客户端突然收到 429，不一定是集群整体过载。这个响应可能是控制面主动切断排队请求，避免几十个挂起的 WATCH、带筛选的 LIST 继续占用 API Priority and Fairness 的 seats，把 etcd 和其他请求一起拖慢。排查时先按请求类型分类，再看 Retry-After、/readyz 和 429 指标，通常比盯着单条错误日志更快。

先判断 429 是保护动作还是普通限流

同样是 429，原因可能不同。API Priority and Fairness 本身会根据 PriorityLevel 和 FlowSchema 控制并发；watchcache 初始化保护则发生在存储缓存尚未准备好、请求继续等待会占住席位的窗口。两者都可能在响应里看到重试提示，所以不要只凭状态码下结论。

先记录请求方法、资源路径、查询参数和时间点。例如 /apis/apps/v1/deployments?watch=true 属于 WATCH，?limit=500 是分页线索，labelSelector 则意味着服务端需要筛选。随后查看客户端是否收到 Retry-After，并把时间与 kube-apiserver 重启、readyz 变化对齐。

按 GET、WATCH、无筛选分页 LIST 分类

KEP-4568 给出的边界可以浓缩为一张排查表：GET 继续处理但可能更慢；WATCH 不再长时间挂起，而是返回 429；LIST 不会一刀切，低成本的无筛选分页请求可以下沉到 etcd，其他 LIST 则可能被拒绝。

这里还有一个容易忽略的差异：watchcache 服务 LIST 时通常可以利用索引，而 etcd 侧需要读取、反序列化并筛选对象；如果集合很大，多个带 selector 的 LIST 同时落到 etcd，代价会迅速放大。分页虽然限制了单页结果，却可能带来连续的下一页请求，因此不能把 limit 简单等同于“请求一定安全”。

理解为什么带筛选 LIST 更容易被拒绝

带筛选的 LIST 不是“多一个参数”这么简单。它要求存储层判断每个对象是否匹配 selector；当缓存没有完成初始化时，服务端无法发挥原有索引和去重能力，只能把压力转给 etcd。此时拒绝请求，是为了保住控制面剩余资源，让写入、健康检查和其他资源类型仍能工作。

客户端侧不要把 429 转化为立即并发重试。Informer 或自研控制器应保留最后的 resourceVersion，遵守 Retry-After，并设置指数退避上限；如果连续重试仍失败，再检查是否只有某个资源类型受影响。把所有 LIST/WATCH 同时重建，反而可能制造下一轮洪峰。

用三组观测信号确认恢复完成

第一组看就绪状态：启动阶段的 PostStartHook 会等待内置资源的 watchcache 初始化，/readyz 长时间不是 200 时，不要把外部流量全部压进 API server。第二组看指标，重点关注 apiserver_request_total{code="429"} 的变化，按 verb、resource 和 client 维度定位是哪一类请求在撞保护边界。第三组看客户端日志，确认重试是否遵守 Retry-After，而不是无延迟自旋。

如果 429 在 readyz 恢复后仍持续增加，才需要继续排查 APF 配置、异常客户端或控制面容量；如果只是某个资源在重初始化期间短暂出现，并且退避后自动恢复，通常属于预期保护行为。只有在确认客户端兼容性或新特性存在问题时，才考虑通过 kube-apiserver 的 feature gate 回滚，并同步观察恢复效果。

常见问题

收到 429 是否说明 etcd 已经不可用？

不能。watchcache 初始化保护本身就会返回 429；需要结合 etcd 健康、readyz、请求资源类型和指标判断。

为什么 WATCH 不能一直等缓存准备好？

长时间挂起的 WATCH 会占用 APF seats。大量客户端一起等待，可能让同一 PriorityLevel 的读写请求都饥饿。

只加大 limit 能避免 429 吗？

不能。无 selector 且带 limit 的 LIST 有机会被委托给 etcd，但带筛选、无界或高成本请求仍可能被拒绝；客户端还要控制翻页和重试并发。