etcd v3.7: RangeStream and What Kubernetes Teams Must Do

etcd v3.7.0 shipped July 8 with the feature large-cluster operators have been waiting years for: RangeStream. The old behavior — buffer the entire LIST response in memory before sending a single byte — is gone. Results now stream in chunks. For teams that have watched kube-apiserver OOM during restarts or sat through agonizing WatchCache initialization on clusters with thousands of objects, this is the fix. Here is what changed, what breaks on upgrade, and when the Kubernetes side of this lands.

The Memory Problem RangeStream Actually Fixes

Every Range request in etcd v3.6 and earlier forced the server to assemble the complete result set in memory before transmitting any of it. On a cluster with 10,000 pods, a LIST call meant etcd held the entire serialized response in RAM simultaneously. The kube-apiserver compounded this: at WatchCache initialization — which happens every time kube-apiserver restarts — it issues paginated LISTs fetching 10,000 items per page and blocks all reads for that resource until the cache fully populates. Run enough of these simultaneously on a large cluster and you end up in the situation documented in Kubernetes issue #115206: kube-apiserver needing 150GB of RAM just to come up.

RangeStream replaces the unary Range RPC with a server-streaming RPC. The server chunks the response internally using adaptive sizing, pins to a single MVCC revision for consistency across all chunks, and derives the total count from a running tally rather than a separate B-tree walk. Memory overhead becomes constant regardless of result set size. The client starts receiving data immediately instead of waiting for a full buffer to fill.

Three Things That Break on Upgrade

v3.7 is not a drop-in upgrade. Check these before touching anything:

Experimental flags are gone. Every flag ever shipped with an --experimental- prefix has been removed. etcd now follows a Kubernetes-style feature gate lifecycle (Alpha → Beta → GA). If your etcd startup configuration contains any --experimental-* argument, the process will refuse to start after upgrade. Audit your config first:

grep "experimental" /etc/etcd/etcd.conf.yaml

v2 API support is fully removed. v2 discovery, v2 request support, and v2 client support are gone. The --snapshot-count flag survives temporarily but disappears in v3.8. If anything in your toolchain still speaks the v2 protocol — old monitoring scripts, legacy clients, custom tooling — it will break.

Architecture-tagged container images no longer exist. The etcd:v3.7.0-linux-amd64 style of tag is discontinued. Switch to manifest-list images that let the container runtime select the right architecture automatically.

What Else Ships in v3.7

RangeStream gets the headline, but three other changes matter for operators:

v2store completely removed. etcd has carried legacy v2store code since the beginning of the v3 era. v3.7 completes that cleanup — bootstrap now uses v3store directly. Years of technical debt gone in one release.

Protobuf overhaul. The deprecated github.com/golang/protobuf and github.com/gogo/protobuf libraries are replaced with the canonical google.golang.org/protobuf, plus a migration to grpc-middleware v2. The result is measurably lower CPU usage and a cleaner dependency graph.

Keys-only Range optimization. Requests that need only keys (not values) now read exclusively from the in-memory index, skipping bbolt backend reads entirely. A meaningful win for workloads that do frequent key-only scans — health checks, index lookups, tooling that lists resources without reading their content.

The Kubernetes Side: EtcdRangeStream Arrives in v1.37

etcd v3.7 ships RangeStream on the server side, but kube-apiserver needs to use it. That happens via the EtcdRangeStream feature gate in Kubernetes v1.37, scheduled for August 26, 2026.

The feature gate arrives as Beta — on by default in v1.37. When active, kube-apiserver switches from paginated Range calls to the streaming RPC for all LIST operations against etcd. Faster WatchCache initialization after apiserver restarts, reduced memory pressure during normal operation.

Critical point: the feature gate does nothing without etcd v3.7 on the backend. The RangeStream RPC does not exist in earlier versions. Upgrade etcd first, then Kubernetes in August. That is the correct sequencing.

Should You Upgrade Now?

If you are running self-managed Kubernetes and experiencing slow apiserver restarts or memory pressure during LIST operations, upgrading etcd to v3.7 now is the right move. Take a snapshot first, audit your config for experimental flags, roll one member at a time, and verify cluster health between each step:

ETCDCTL_API=3 etcdctl snapshot save /backup/etcd-$(date +%Y%m%d).db   --endpoints=https://127.0.0.1:2379   --cacert=/etc/kubernetes/pki/etcd/ca.crt   --cert=/etc/kubernetes/pki/etcd/server.crt   --key=/etc/kubernetes/pki/etcd/server.key

If you are on a managed Kubernetes service — EKS, GKE, AKS — wait for the managed upgrade path. Do not touch etcd directly on managed clusters. If you are on etcd v3.6 below v3.6.11, upgrade to v3.6.11 first; there are intermediate fixes you should not skip.

The full picture: etcd v3.7 now, Kubernetes v1.37 on August 26, and large clusters get end-to-end streaming for their most memory-intensive operations. The context on the Kubernetes client side — streaming LIST encoding landed in v1.33 — is now matched by streaming on the etcd side. The architecture is finally correct end to end.