etcd v3.7.0 Released: RangeStream, Performance Gains, and the End of v2store

The SIG etcd release of v3.7.0 marks a significant evolution for the distributed key-value store, focusing on architectural modernization and operational efficiency. This minor release removes the final dependencies on the legacy v2store, completing a multi-year transition toward a unified v3store bootstrap process. Engineers should note that while v3.7.0 continues to generate v2 snapshots for backward compatibility, the --snapshot-count flag and v2 snapshot support are slated for removal in v3.8.0.

Performance and scalability are central to this release, introduced through several high-impact architectural changes:

• RangeStream: Mitigates memory pressure and latency spikes by allowing clients to retrieve large result sets in chunks rather than buffering entire responses.
• Keys-only Range Optimization: Eliminates backend disk reads by serving key-only queries directly from the in-memory index, unless value-based sorting is required.
• Lease Enhancements: Improves cluster stability under load by prioritizing LeaseRevoke requests and introducing FastLeaseKeepAlive to reduce latency in linearizable lease renewals.
• Protobuf Overhaul: Migrates the codebase to google.golang.org/protobuf, replacing deprecated libraries. This refactor improves maintainability and yields measurable CPU efficiency gains.

The release incorporates updated core dependencies, specifically bbolt v1.5.1 and raft v3.7.0. The bbolt update introduces granular control over database file size limits and performance tuning via the NoStatistics setting, which reduces lock contention.

Deployment Considerations:

• Container Images: Official images are now distributed exclusively as multiarch containers; architecture-tagged image support has been discontinued.
• API Breaking Changes: Developers integrating the etcd Go modules should audit their codebase for impacts resulting from the protobuf migration and the removal of the grpc.WithBlock dial option.
• Experimental Flags: All --experimental flags have been removed in favor of the Kubernetes-style feature-gate lifecycle.

Source code, binaries, and official container images are available for immediate implementation. Organizations are advised to perform rolling upgrades, validating cluster health at each step, and to review the official changelog for detailed migration paths.

In etcd v3.6 and earlier, the system architecture for range requests required the database to buffer entire result sets in memory before transmitting them to the client. This legacy approach created significant challenges for high-throughput environments, specifically causing unpredictable latency and spikes in memory consumption on both the server and the client side whenever large result sets were queried.

The introduction of RangeStream in etcd v3.7 addresses these limitations by shifting from an atomic response model to a streaming RPC model. By sending result sets in discrete chunks, RangeStream allows calling applications to process data incrementally. This transition provides several critical operational advantages:

• Predictable Memory Utilization: By capping the memory footprint required to hold pending responses, applications can maintain stability even when retrieving massive volumes of keys.
• Reduced Latency: Clients can begin processing the initial segments of a result set immediately upon receipt, rather than waiting for the entire set to be buffered and serialized.

To implement this functionality, engineers can utilize RangeStream via gRPC or directly through the etcdctl command-line interface. Detailed implementation instructions, including necessary modifications for client-side consumption, are provided in the official etcd documentation.

Looking ahead, this streaming capability is slated for broader integration within the Kubernetes ecosystem. Users running the upcoming Kubernetes v1.37 release will be able to leverage RangeStream functionality by enabling the EtcdRangeStream feature gate. This adoption reflects the ongoing convergence of etcd and Kubernetes development, designed to enhance the performance and reliability of the underlying control plane for large-scale cluster operations.

etcd v3.7.0 targets control-plane efficiency by reducing backend reads, lowering lease-management latency, and improving watch-path concurrency. For Kubernetes operators, the cumulative effect is expected to be a significant decrease in CPU usage by etcd members relative to v3.6.

Keys-only Range optimization. A Range request with keys_only returns keys only; previously the server still traversed bbolt and loaded serialized values. The optimization in #21791 lets etcd serve such requests entirely from its in-memory index, avoiding value deserialization and reducing memory pressure. The one exception is when SortTarget is VALUE: ordering by value still requires loading values from bbolt. Practical example: etcdctl get --keys-only against a large key space, or control-plane logic that enumerates keys before fetching specific records—these workflows now generate far less backend I/O.

Faster, more reliable leases. Lease expiration previously competed with normal traffic; #20492 prioritizes LeaseRevoke requests so expiration remains timely even under overload. The FastLeaseKeepAlive path (#20589) reduces renewal latency by skipping the wait for the applied index in the older keepalive flow. For example, pods with short leases or controllers generating frequent lease traffic benefit from lower keepalive latency and more deterministic revocation.

Faster find() for watches. Concurrent watches on keys rely on interval-tree lookups. #19768 splits the interval tree by right endpoint on matched left endpoints, reducing traversal cost when many watches share key ranges. This matters for operators, controllers, or client-side caches watching overlapping key prefixes.

Recommended actions:

• Use keys-only requests wherever values are not needed; expect bbolt reads only when sorting by value.
• For clusters with high churn or large pod counts, test the FastLeaseKeepAlive feature and validate lease and watch metrics.
• Review the v3.7 upgrade guide; perform a rolling upgrade one member at a time and confirm cluster health between steps.

etcd v3.7 removes the last startup dependency on the legacy v2 store. The server now bootstraps entirely from the v3 store (#20187), meaning the v2store code path is no longer exercised during server initialization. This eliminates long-standing technical debt and simplifies the bootstrap workflow. Backward compatibility is preserved: v3.7 continues to generate v2 snapshots, and the --snapshot-count flag remains available. This is the final remaining v2 dependency; both v2 snapshot generation and the flag are scheduled for removal in v3.8. Additionally, legacy v2 packages such as v2 discovery (#20109), v2 request handling (#21263), and v2 client support (#20117) have been removed, which may create breakage for users who have not updated to v3.6.11 or later.

The protobuf layer was migrated (#14533) from github.com/golang/protobuf and github.com/gogo/protobuf to the fully supported google.golang.org/protobuf API. Concurrently, gRPC logging moved to grpc-middleware v2 (#20420). These changes improve security and maintainability and reduce CPU usage in etcd components. For example, a client importing go.etcd.io/etcd/api/v3/etcdserverpb may need to regenerate or update generated message types to the new module path and adjust for API differences in the proto package. Official binaries and container images are unaffected, but Go module consumers—particularly those depending on the client SDK or packages under api/ and pkg/—may need dependency updates.

Practical checklist for Go module consumers:

• Update imports from github.com/golang/protobuf and github.com/gogo/protobuf to google.golang.org/protobuf.
• Rebuild generated protobuf code with protoc-gen-go from the new module, then recompile against etcd v3.7 API types.
• Audit gRPC interceptor dependencies for grpc-middleware v2 API changes, particularly logging middleware constructors.
• Remove any code paths that relied on v2 discovery or v2 request handling, as these packages no longer exist.

These refactors align with the Kubernetes-style feature-gate lifecycle; all deprecated --experimental-* flags were removed in v3.7, so configurations must migrate to stable flags or feature gates before upgrading.

etcd v3.7 adds Unix socket endpoint support (#19760). Client and peer URLs may now use the unix:// scheme, allowing local communication over a Unix domain socket instead of a TCP port. Because the feature is restricted to single-member clusters, it is aimed at development, testing, and edge-device deployments. Example: etcd --listen-client-urls unix:///var/run/etcd.sock.

All etcdutl commands now accept a timeout argument (#20708). Previously, offline utility commands could block indefinitely while acquiring a lock. Operators should pass an explicit timeout, such as etcdutl snapshot restore --timeout 30s, to bound execution.

Client v3 now permits setting a JWT directly (#16803). When a token is set explicitly, automatic authentication retries are disabled (#20747), so applications managing their own tokens must handle refresh and retry logic themselves. Additionally, the AuthStatus API no longer requires prior authentication (#20802); clients can check authentication status without triggering a permission check, removing overhead during early connection setup.

Watch-path observability is extended with new send-loop metrics (#21030):

• etcd_debugging_server_watch_send_loop_watch_stream_duration_seconds
• etcd_debugging_server_watch_send_loop_watch_stream_duration_per_event_seconds
• etcd_debugging_server_watch_send_loop_control_stream_duration_seconds
• etcd_debugging_server_watch_send_loop_progress_duration_seconds

These complement the new etcd_server_request_duration_seconds metric (#21038) for server-wide request latency tracking.

The etcdctl command tree was reorganized for clarity (#20162), and global command-line flags are now hidden to streamline help output (#20493). Scripts that depend on positional subcommand arguments should be validated against the new structure.

etcd v3.7 bundles bbolt v1.5.1, which adds:

• File size limits: operators may set a limit; bbolt refuses writes once the limit is exceeded until the database is compacted or the limit is increased.
• NoStatistics: disables statistics-gathering locks, reducing overhead for high-throughput workloads.
• Efficient hashmap processing: interval span merging completes faster and with less overhead.

Upgrading to v3.7.0 requires careful orchestration due to significant architectural changes. To ensure cluster stability, perform a rolling upgrade one member at a time, verifying full cluster health and quorum synchronization between each node replacement. Before initiating the upgrade, review the official upgrade guide and API documentation to identify potential impacts on your specific deployment environment.

The v3.7.0 release mandates the following critical transitions:

• Removal of Legacy v2 Components: Direct support for v2 discovery (#20109), v2 request handling (#21263), and the internal v2 client libraries (#20117) has been removed. Environments still dependent on v2-era components must complete migration to v3 APIs prior to updating.
• Feature Flag Normalization: All deprecated experimental flags have been removed (#19959). Moving forward, etcd utilizes a Kubernetes-style feature-gate lifecycle. Replace any legacy --experimental-* flags with their stable counterparts or the relevant feature gates.
• Non-blocking Client Initialization: The grpc.WithBlock dial option is no longer honored (#21942). Applications relying on blocking client creation will need to be refactored; refer to the grpc-go anti-patterns documentation for recommended architectural adjustments to handle non-blocking connection states.
• Container Image Distribution: Official container images are now exclusively multiarch. Architecture-specific image tags are no longer published. CI/CD pipelines and deployment manifests (e.g., Kubernetes image fields) must be updated to pull from the multiarch manifest list to prevent deployment failures.

Engineering teams utilizing etcd Go modules should also perform a thorough dependency audit. The transition from legacy protobuf libraries (github.com/golang/protobuf and github.com/gogo/protobuf) to google.golang.org/protobuf may necessitate refactoring of custom client-side code interacting with the etcd API. Ensure your environment is aligned with these upstream changes to maintain compatibility with the updated underlying storage and consensus logic.