Kubernetes v1.37 如何降低 Watch Cache 重建时的 etcd 流量尖峰

控制面刚重启，业务还没完全恢复，kube-apiserver 却先把大量 list/watch 请求压向 etcd，这是大型集群恢复期很容易被忽略的一段风险。Kubernetes v1.37 的发布说明把 Watch Cache 初始化与重建的韧性工作推进到稳定状态：缓存升温期间请求会被有界处理，超出承载范围的请求返回 HTTP 429，而不是任由请求堆积把控制面拖入更深的故障。

这项变化的核心不是“etcd 变快了”，而是 kube-apiserver 在 Watch Cache 尚未准备好时主动控制 list/watch 流量。升级后，控制器和 Operator 必须把 HTTP 429 当成可恢复信号，读取 Retry-After 并执行指数退避。

v1.37 改变的是恢复期的流量形状

Watch Cache 位于 API Server 和 etcd 之间，用来承接资源的 list/watch 访问。正常运行时，控制器大多从缓存读取；但 API Server 启动或缓存需要重新建立时，这条路径会短暂变得敏感：多个资源类型的请求可能同时触发初始化，客户端也可能因为连接断开而集中重连。

Kubernetes v1.37 的发布说明明确提到，ResilientWatchCacheInitialization 在更早版本已经稳定，v1.37 则把剩余的 WatchCacheInitializationPostStartHook 稳定并锁定。缓存初始化和重初始化不再制造对 etcd 的流量尖峰，请求会在缓存升温期间被更温和地处理。

为什么“返回 429”反而比请求堆积更安全

如果所有 list/watch 都在缓存未就绪时继续向下游推进，短时间内的并发量会同时消耗 etcd 和 API Priority and Fairness 的容量。请求表面上没有被拒绝，实际却可能把延迟、连接数和排队长度一起推高，最终影响已经在运行的工作负载。

v1.37 的处理方式是让 kube-apiserver 只放行有界请求，无法安全承接的请求以 HTTP 429 返回。429 在这里是背压信号：它告诉客户端“现在暂时没有足够的恢复容量”，而不是声明资源不存在或请求格式错误。对自定义控制器来说，记录这一类响应并不代表服务已经失败，关键是后续是否有节制地重新建立 watch。

控制器需要把哪几类失败分开

• HTTP 429：按 Retry-After 等待，若没有可用值则使用带抖动的指数退避。
• 连接断开或 watch 结束：重新建立 watch，并从资源版本或控制器自身的恢复逻辑继续。
• 权限、参数和资源不存在：这些不是恢复期背压，不能套用无限重试。

升级时先按负载和约束判断收益

最直接受益的是资源种类多、控制器数量大、滚动升级或故障恢复时会出现大量重连的集群。小型集群也能获得更平滑的恢复行为，但如果真正的瓶颈是 etcd 磁盘延迟、网络丢包或控制器本身的重试风暴，单靠 v1.37 不会替代容量治理。

可以用下面的判断把升级收益和问题边界分开：

上线后的最小验收路径

发布窗口不要只确认 kube-apiserver 的 Pod 变成 Running。至少要安排一次可观察的恢复演练：记录控制面重启前后的 list/watch 速率，检查 etcd 是否出现异常尖峰，观察控制器收到 HTTP 429 后是否按退避重试，最后确认工作负载和自定义资源都能重新收敛。

验收结果最好同时保留四类证据：API Server 的恢复日志、etcd 的请求与延迟曲线、控制器的 429/重试计数，以及最终资源状态。这样才能区分“缓存恢复平滑”和“客户端恰好没有报错”这两个完全不同的结果。

如果控制器由团队自行维护，升级前应先检查 HTTP 客户端或 watch 封装是否把 429 当作普通不可重试错误；升级后再检查退避是否会因为多个 goroutine 同时失败而重新同步。这里别急着把重试上限调大，先确认失败是否被摊平。

常见问题

Kubernetes v1.37 会消除所有 etcd 流量尖峰吗？

不会。它针对的是 Watch Cache 初始化和重初始化造成的恢复期压力，etcd 的磁盘、网络、请求模型和其他客户端仍然需要单独治理。

HTTP 429 是否说明 Kubernetes 资源有问题？

不一定。在这个场景里，429 更可能表示 API Server 正在执行有界背压。客户端应先读取 Retry-After 并退避，再根据后续响应判断是否存在真正的资源或权限错误。

升级后最值得先看哪项指标？

先把 API Server 的 429、list/watch 延迟、etcd 请求速率和控制器重试次数放在同一时间线上观察，重点看控制面恢复后的收敛速度和是否出现二次重试风暴。

把这次发布变化落到值班清单

Kubernetes v1.37 的 Watch Cache 改进适合作为控制面恢复能力的一部分纳入升级验收：确认版本变化，演练重启，验证 429 的背压路径，检查控制器的 Retry-After 与 exponential backoff，最后用资源收敛结果闭环。这样得到的是一条可复查的恢复链路，而不是只记住“缓存初始化更稳定”这一句发布摘要。