Distributed Systems
etcd: a Raft-replicated key-value store for coordination data
etcd-io/etcd on GitHub
By Mira Vance
Published 22 October 2026 · Last reviewed 22 October 2026
etcd 3.7.0 boots entirely from the v3 store and removes the v2 store outright; the only way there is a rolling upgrade from a cluster already on v3.6.11 or later, because etcd upgrades one minor version at a time.
Drafted with AI assistance, researched, verified and edited by the HastCode editorial team. We publish only as many pieces as the Author can verify this way.
TL;DR
• etcd is a distributed, reliable key-value store for the most critical data of a distributed system: a Go server that uses Raft to keep one replicated log across an odd number of members.
• Writes are linearizable and durable by default, every key keeps its history under multi-version concurrency control, and watches are ordered, reliable and resumable: the three things the project's own comparison page says ZooKeeper and Consul lack.
• It is sized for coordination data, not for a database: a 2 GiB default quota, 8 GiB suggested maximum and 1.5 MiB per request.
• Adopt it, with or without Kubernetes, for configuration, service discovery, locks and leader election on dedicated SSD-backed machines. Past a few gigabytes, or when you need SQL, the project itself points you to a NewSQL database.
In 60 seconds
These commands from the README's Running etcd section assume a release binary unpacked to /tmp/etcd-download-test. They move it onto the path, start a single member listening on 2379 for clients and 2380 for peers, then write and read one key with etcdctl. The Go client is a separate go get.
Architecture
Walk the diagram left to right. A client talks gRPC on port 2379 to six services: KV, Watch, Lease, Auth, Cluster and Maintenance. Anything without gRPC uses the gRPC gateway, which turns HTTP/JSON under /v3/ into the same calls. The client does not need to know which member leads: followers forward writes to the leader.
A write enters Raft. The leader appends the proposal to its write-ahead log under member/wal/ and replicates it to peers on port 2380; it commits once a majority of members has persisted it. Each write is fsynced to the log, which is why the FAQ treats disk latency as part of leader liveness.
Committed entries are applied to the MVCC store. Its physical form is member/snap/db, a bbolt B+tree whose entries are keyed by revision, not by user key, so old versions stay readable until compaction removes them; a consistent_index in the file records how far the log has been applied. A secondary in-memory btree index maps each key to its revisions.
Reads are linearizable by default and go through quorum; a serializable read is served locally by any member and may be stale. Watches stream PUT and DELETE events by revision, and leases delete their keys when a client stops sending keep-alives.
Signals
Use it if
• You need a small, strongly consistent store for configuration, service discovery, locks or leader election: the comparison page frames etcd as "distributed system coordination and metadata storage", and the server ships Lock and Election RPCs whose keys and revisions you can check inside a transaction.
• You want to run it without Kubernetes and wonder whether anyone does: the project's adopters list has Vonage on "vault backend, system configuration for microservices, scheduling, locks", Grab and Yandex on "system configuration for services, service discovery", and PingCAP's PD, which embeds it.
• You want history you can trust: MVCC keeps every revision until compaction, and watches are ordered, unique, reliable and resumable within that history.
• You can give it dedicated, SSD-backed machines: the hardware guide calls fast disks the most critical factor and starts its sizing table at two vCPUs and 8 GB for under 200 requests a second.
Don't use it if
• You are storing more than a few gigabytes or need SQL: the project says choose a NewSQL database such as CockroachDB or TiDB. The default quota is 2 GiB, 8 GiB the suggested maximum; past it, etcd raises a NOSPACE alarm and accepts only reads and deletes.
• You want the whole service-discovery product: Consul bundles health checks, failure detection and DNS, which etcd leaves to you; use Consul, and keep etcd for the consistent store underneath.
• You expect Lock alone to fence an external resource: the Jepsen write-up says the etcd lock only safely guarantees mutual exclusion inside etcd's own keyspace and transactions with revision checking; carry the lock key's revision into the resource as a fencing token, or let the resource lock itself.
• Your members must span regions or share slow disks: the FAQ says disk latency is part of leader liveness, by design, and cross-region clusters pay in consensus latency and retuned timeouts. The NewSQL class is built to scale across data centers; use it there.
Alternatives
• Apache ZooKeeper: solves the same coordination problem on the JVM with its own Jute RPC protocol; no multi-version data model, no linearizable reads, and membership reconfiguration only in versions above 3.5.0.
• HashiCorp Consul: an end-to-end service discovery framework with health checks and DNS, whose key-value API lacks multi-version keys, conditional transactions and reliable streaming watches.
• CockroachDB: the NewSQL answer, SQL over terabytes across data centers, with read linearization that rests on clock barriers rather than one network round trip.
• TiDB: the other NewSQL database etcd names; its placement driver, PD, embeds etcd for its own metadata.
Changelog
• v3.7.2 22 September 2026
• v3.6.15 22 September 2026
• v3.5.34 22 September 2026
• v3.7.1 23 July 2026
• v3.6.14 23 July 2026
• v3.5.33 23 July 2026
• v3.7.0 8 July 2026
• v3.6.13 1 July 2026
• v3.5.32 1 July 2026
• v3.7.0-rc.0 1 June 2026 pre-release
FAQ
Is etcd production ready?
Yes. etcd patches three minor branches at once, and its consistency has been checked by Jepsen and by deterministic fault injection; Linux on AMD64 and ARM64 are its Tier 1 platforms.
Can I use etcd without Kubernetes?
Yes. etcd's adopters list names Vonage, Grab, Yandex and Qiniu using it for configuration, discovery and locks, and Patroni, Apache APISIX, CoreDNS and Vitess build on it.
How much data can etcd store?
A few gigabytes. etcd's default quota is 2 GiB, 8 GiB the suggested maximum, 1.5 MiB per request; past the quota it stops accepting writes until you compact, defragment and disarm.
How many etcd members do I need?
Three or five. etcd needs a majority: three members tolerate one failure, five tolerate two, an even count adds nothing, and the FAQ suggests no more than seven.
What are the alternatives to etcd?
etcd's own comparison names Apache ZooKeeper (same problem, JVM, no MVCC), HashiCorp Consul (a discovery framework with a weaker key-value API) and NewSQL databases such as CockroachDB and TiDB (SQL, terabytes).
How does etcd compare to Consul?
etcd's comparison page says Consul's key-value API "lacks multi-version keys, conditional transactions, and reliable streaming watches" and calls etcd "a better choice over Consul" for a consistent store; Consul wins when you want health checks and DNS.
Who maintains etcd, and how is it licensed?
etcd is Apache 2.0, a CNCF project and a Kubernetes Special Interest Group, SIG-etcd; Signals has its contributors and releases.
Verdict
Adopt etcd outside Kubernetes when the data is coordination-sized and the guarantees are the point: configuration, service discovery, locks and leader election for a few gigabytes at most, on three or five dedicated, SSD-backed members in one data center. You get linearizable writes, revision history, reliable watches and a release train that patches three minor branches at once, in one Go binary that the Kubernetes project now maintains as SIG-etcd. We would not adopt it as a general database, for anything near the 8 GiB ceiling, or with a bare Lock guarding an external resource. A supported storage ceiling well past 8 GiB would widen that recommendation; a slip in the three-branch patch cadence, visible in Changelog, would narrow it.
Sources
• Upgrade etcd from v3.6 to v3.7
• etcd patch releases v3.7.2, v3.6.15 and v3.5.34
• etcd versus other key-value stores
• etcd API
• etcd persistent storage files
• etcd concurrency API reference
• etcd hardware recommendations
• etcd FAQ
• Latest Jepsen results against etcd 3.4.3
• Autonomous testing of etcd's robustness
• etcd.io
• https://github.com/etcd-io/etcd
• https://github.com/etcd-io/etcd/releases
• https://github.com/etcd-io/etcd/graphs/contributors
• https://github.com/etcd-io/etcd/tree/main/.github
• https://github.com/etcd-io/etcd/blob/main/README.md
Get new Explainers by email
How real systems are built, in your inbox. No spam; unsubscribe any time.
More in Distributed Systems
1. ConceptMetastable failures: why systems stay down after the trigger is goneA metastable failure outlives its trigger because a loop such as retries keeps the system overloaded. How the loop works and what breaks it.26 October 2026
2. Repo ProfileApache Iggy: a persistent message stream in RustApache Iggy is a Kafka-shaped message streaming log in one Rust binary, built for tail latency; pre-1.0, so upgrades need a fresh data directory.22 October 2026
Related
1. ComparisonConnection reuse in HTTP/1.1, HTTP/2 and HTTP/3: how each works and where each breaksHow HTTP/1.1, HTTP/2 and HTTP/3 reuse connections, where each one breaks, and which to use for calls between services.26 October 2026
2. Case StudySingle-tenant Titus: how Netflix gives one container its own VMHow Netflix's Titus gives a few noisy or sensitive workloads a dedicated, right-sized EC2 instance under the same container API, and what that costs.26 October 2026
3. Repo ProfileAgentgateway: a Rust gateway for HTTP, gRPC, MCP and LLM trafficAgentgateway is a Rust proxy that routes HTTP, gRPC, MCP, A2A and LLM traffic under one Gateway API control plane; minor releases still break config.22 October 2026