Kubernetes v1.37：etcd RangeStream 降低大规模列表读取的内存占用
内容提要
etcd RangeStream在Kubernetes v1.37中升级为beta，配合etcd v3.7，通过流式分块读取减少API服务器和etcd的内存占用，使峰值使用更可预测。它替代分页Range，按字节而非键数限制块大小，边读边释放内存。默认启用，若etcd较旧则自动回退。
延伸解读
为什么按字节分块更优
传统分页按键数限制，但对象大小不一，大对象页面可能仍占用大量内存。RangeStream按字节动态调整块大小，使内存使用更可预测，避免因并发读取大对象导致OOM。
自动回退机制
API服务器在启动时检测etcd版本，若低于v3.7则自动使用旧的分页Range路径。运行时若收到Unimplemented错误也会回退，无需手动配置，兼容性良好。
如何确认功能生效
通过监控etcd指标中operation="listStream"的计数，非零表示RangeStream正在使用。若始终为零，则说明API服务器仍在使用分页Range，通常是因为etcd版本过旧。
Q&A
Kubernetes v1.37 中 etcd RangeStream 的主要作用是什么？
etcd RangeStream 在 Kubernetes v1.37 中升级为 beta，配合 etcd v3.7，通过流式分块读取减少 API 服务器和 etcd 在读取大规模集合时的内存占用，使峰值内存使用更可预测。
为什么 Kubernetes API 服务器需要从 etcd 读取整个资源集合？
API 服务器主要从内存中的 watch 缓存提供列表和监视请求，而填充该缓存需要从 etcd 读取资源的完整状态，这在启动和每次重新初始化时都会发生。
etcd RangeStream 与之前的分页 Range 读取相比有什么改进？
分页 Range 按键数限制每页大小，但无法感知对象大小，导致大对象页面可能很大，内存使用难以预测。RangeStream 按字节限制块大小，并自适应调整，边读边释放内存，使内存使用更可预测。
etcd RangeStream 是如何工作的？
RangeStream 是 etcd v3.7 新增的流式 RPC，它接受与 Range 相同的 RangeRequest，但将结果集分成多个块并流式传输，而不是一次性构建整个响应。块大小根据返回值自适应调整，内存随流式处理逐步释放。
如何启用或禁用 etcd RangeStream？
RangeStream 默认启用，通过 kube-apiserver 的 EtcdRangeStream 特性门控控制，该门控在 v1.37 中为 beta 且默认开启。如需禁用，可设置 --feature-gates=EtcdRangeStream=false。
如果 etcd 版本低于 v3.7，API 服务器会如何处理？
API 服务器在启动时会检测 etcd 是否支持 RangeStream，并在运行时如果调用返回 Unimplemented 也会自动回退到分页 Range 路径，因此无需手动配置。
如何确认 API 服务器是否正在使用 RangeStream？
可以通过 etcd 指标确认，如果 etcd_request_duration_seconds_count 中 operation="listStream" 的计数非零，则说明 RangeStream 正在使用；如果始终为零，则可能因为 etcd 版本低于 v3.7 而仍在使用分页 Range。
