Kubernetes v1.37 etcd RangeStream 大列表如何降低内存

Kubernetes 控制面在大集群启动或 watch cache 重新初始化时，最怕一次性读取大量对象：etcd 先拼出完整的 Range 响应，API Server 又要暂存并解码，峰值会同时落在两端。Kubernetes v1.37 把 etcd RangeStream 提升为 Beta，配合 etcd v3.7+ 后，集合会按分块流式返回，能降低大列表读取的瞬时内存占用。关键不是给业务对象加一个参数，而是确认版本、代理和指标三件事。

官方资料：https://kubernetes.io/blog/2026/09/01/kubernetes-v1-37-etcd-range-stream/

大列表为什么会把内存峰值推高

旧的 unary Range 调用要先在 etcd 侧组成完整响应，再通过 gRPC 发给 API Server。大量对象同时存在于原始键值、序列化 protobuf 和发送缓冲区中，API Server 接收后还要解码并填充 watch cache。分页只能把一次请求切小，单页对象大小仍可能差异很大；而且每页的总数计算也会带来额外扫描成本。

RangeStream 的改变是服务端按块返回结果，API Server 读到一块就处理一块。每个块包含不重复的键值，所有块使用同一个 revision，因此不会因为流持续时间较长就把后续写入混进同一份快照。它解决的是读取过程的峰值和可预测性，不是删除对象、压缩数据库或替 API Server 解决所有内存问题。

先核对 v1.37、etcd v3.7 和代理能力

部署判断可以按下面的顺序做。Kubernetes v1.37 是 API Server 侧的接入版本，etcd v3.7 才提供对应的 RangeStream RPC；如果使用 etcd gRPC proxy 或其他兼容后端，还要单独确认它是否实现该 RPC。官方 etcd API 文档明确说明，RangeStream 不支持自定义排序、revision 过滤器，也不支持通过 gRPC proxy 转发。

默认开关不必乱改，异常时再显式回退

v1.37 中 EtcdRangeStream 为 Beta 且默认开启。正常升级时，先检查现有参数是否把它关闭即可，不要为了追求“启用”而重复添加一串 feature gate。只有 etcd 兼容后端无法正确处理流式 RPC，或者观察到代理层异常时，才在 kube-apiserver 参数中明确关闭：

# 只在兼容后端无法正确回退时使用；正常 v1.37 默认开启
--feature-gates=EtcdRangeStream=false

原生 etcd 版本过低时，API Server 会识别 gRPC 的 Unimplemented 并自动回到分页读取，行为不会因为一次升级就突然改变。关闭开关会牺牲流式读取的内存收益，但适合用来隔离代理问题。调整控制面参数前应保留原启动配置，并按集群发行版的方式滚动更新。

用 listStream 指标确认流式读取已经发生

不要只看启动参数判断成功。Kubernetes 官方运维文档建议观察 etcd 请求指标中的 operation="listStream"。可以把下面的 PromQL 放进控制面观测面板：

# 查询流式列表请求的累计次数；用于确认实际请求路径
sum(etcd_request_duration_seconds_count{operation="listStream"})

计数非零，说明 API Server 至少已经走过 RangeStream 路径；计数长期为零，优先排查 etcd 是否仍为 v3.6 或更早版本、代理是否不支持该 RPC，以及 feature gate 是否被关闭。已有按 operation="list" 匹配的面板和告警也要同步纳入 listStream，否则升级后可能漏掉新的请求类型。

上线时要把收益和边界一起验收

建议先在非生产控制面观察一次 watch cache 初始化或资源列表恢复过程，记录 etcd 与 API Server 的峰值、持续时间和 listStream 变化，再安排滚动升级。RangeStream 的快照 revision 会在流开始时固定；如果流期间该 revision 已被 compaction，API Server 会把它当作 cache 初始化失败并重试，这不是把 compaction 变成永久故障。

验收重点是“是否减少读取峰值、是否保持列表结果一致、是否能回退”。它不会替代 etcd 备份、碎片整理、容量规划，也不会自动降低对象数量。对于不支持排序或 revision 过滤的直接 etcd 客户端调用，继续使用普通 Range 或按业务限制读取，不要把 etcdctl get --stream 当成所有查询的无条件替代。

相关问题

只有升级 Kubernetes v1.37，不升级 etcd 可以吗？

可以继续工作，但 etcd 低于 v3.7 时无法提供 RangeStream，API Server 会回退到分页 Range，因此不会得到这项流式读取的收益。

为什么 listStream 指标还是零？

常见原因是 etcd 版本过低、代理不支持该 RPC、feature gate 被关闭，或当前还没有触发对应的大列表读取。应结合 API Server 参数和 etcd 支持情况判断。

RangeStream 会不会让列表结果前后不一致？

正常完成的流会固定同一 revision，并按块拼出与 Range 相同的结果集。流中遇到 compaction 或其他错误时，API Server 会按 cache 初始化失败处理，而不是提交半份结果。