Kubernetes 1.37 的 RangeStream 进入 Beta：大规模 List 请求为什么更省内存

Kubernetes 1.37 把 EtcdRangeStream 提升到 Beta，并在满足条件时默认启用。它没有改变 List 返回的数据集合，而是让 API Server 与 etcd 以流式分块方式搬运大型集合，减少双方同时持有整页响应带来的峰值内存。要得到实际收益，集群至少需要 Kubernetes 1.37 与 etcd 3.7；较旧的 etcd 会自动回退到原有分页 Range 路径。

这次变化解决的是什么

API Server 的多数 List 与 Watch 请求会使用内存中的 watch cache，但缓存初始化或重建仍要从 etcd 读取某类资源的完整状态。旧路径虽然会分页，却主要按键数量控制一页大小；当 Pod 等对象本身很大时，同样数量的一页可能占用远超预期的内存。

更麻烦的是，etcd 的一元 Range 要先组装完整页面再发送，API Server 解码期间也会保留这份负载。对象尺寸与并发读取叠加后，etcd 和 API Server 的峰值容易同时升高，严重时可能触发 OOM。

RangeStream 如何压低峰值内存

etcd 3.7 新增的 RangeStream 接收相同的 RangeRequest，也返回相同结果集，但不会先把整页结果装配完成。它会根据值的大小自适应切成多个块，发送一块、解码一块、释放一块，使内存上界更接近字节规模，而不是对象数量。

这个差异对小集合未必明显，却特别适合对象数量多、单体尺寸大，或缓存重建与直接读取并发出现的集群。它优化的是数据搬运方式，不会替代 watch cache，也不会减少 Kubernetes 必须读取的对象数量。

平台团队升级前要核对什么

Kubernetes 1.37 的发布说明列出 67 项增强，其中 16 项进入 Stable、23 项进入 Beta、27 项进入 Alpha，另有 1 项弃用或移除。RangeStream 只是其中一项，因此升级判断不能只看“默认开启”，还要把控制面版本、etcd 版本和回退行为放在同一张检查表里。

• 版本：确认 API Server 已到 1.37，etcd 已到 3.7；滚动升级期间允许暂时回退。
• 门禁：检查 EtcdRangeStream 是否保持默认启用，避免配置模板意外关闭。
• 容量：比较升级前后控制面内存峰值和重启次数，不能只观察平均值。
• 回滚：保留关闭特性门禁的路径，但不要把关闭门禁当成替代 etcd 升级的长期方案。

怎样确认流式读取已经生效

官方给出的直接观测点是 API Server 的 etcd 请求指标。etcd_request_duration_seconds_count{operation="listStream"} 出现非零计数，说明流式读取路径已被使用；如果一直为零，应先检查 etcd 是否低于 3.7，再检查特性门禁，而不是立即把原因归结为“没有大 List 请求”。

验证时还要把峰值内存、List 延迟与回退日志一起看。指标出现只证明路径被调用，不能单独证明每个工作负载都获得同样幅度的节省。更稳妥的做法是选取对象多、体积大的资源类型，在相同负载窗口对比升级前后的控制面曲线。

常见问题

RangeStream 会改变 List 接口返回内容吗？

不会。它改变的是 etcd 到 API Server 的传输与释放方式，RangeRequest 和最终结果集保持一致，客户端无需因为分块传输修改业务逻辑。

只升级 Kubernetes 1.37，不升级 etcd 3.7 可以吗？

集群可以继续工作，但无法获得 RangeStream 的流式读取收益。API Server 会在启动探测或运行时遇到不支持时回退到原分页 Range 路径，因此应把 etcd 版本纳入升级计划和验收记录。