News › performance
By Zayden R., September 2, 2026
Kubernetes v1.37 introduces etcd RangeStream in beta, reducing memory usage for large list reads. This update, paired with etcd v3.7, makes API server memory management more predictable and efficient.
Kubernetes has rolled out version 1.37, featuring a significant update that promises to enhance memory efficiency for engineers managing large data sets. The introduction of etcd RangeStream, now in beta, is designed to reduce the memory footprint when the API server and etcd perform large list reads. This update is particularly relevant for those dealing with substantial collections of resources such as Pods.
Traditionally, the API server handles list and watch requests using an in-memory watch cache, which requires reading a resource's complete state from etcd. This process is resource-intensive, especially when dealing with large or numerous objects. While the API server had previously implemented pagination to manage these reads, it was based on key count, lacking awareness of object size. This could lead to unpredictable memory usage and potential out-of-memory (OOM) errors.
Enter etcd v3.7, which brings with it a new streaming capability through the RangeStream RPC. Unlike the previous unary Range method, which assembles a complete page before transmission, RangeStream breaks the response into manageable chunks. These chunks are streamed progressively, allowing memory to be freed as the data is processed. This adaptive chunking helps ensure that memory usage is bounded by bytes, not simply a key count.
For Kubernetes users, this means that when the EtcdRangeStream feature gate is enabled on the kube-apiserver (enabled by default in v1.37), the server will utilize RangeStream for reading full collections from etcd. This applies to watch cache initialization and scenarios where list requests bypass the cache and access etcd directly. The API server processes each chunk upon arrival, releasing memory before fetching the next, ensuring that neither it nor etcd holds the entire collection at once.
To leverage this enhancement, users must ensure they are running Kubernetes v1.37 or later, alongside etcd v3.7 or newer. The system is designed to gracefully fall back to the older paginated Range method if necessary, ensuring compatibility with existing setups. Sysadmins who have been grappling with memory unpredictability will find this a solid improvement, offering a more efficient and predictable system.