etcd: Distributed Key-Value Store for Critical Data

What etcd is

etcd is a distributed, reliable key-value store for the most critical data of a distributed system. The project's FAQ describes it as a consistent distributed key-value store, mainly used as a separate coordination service and designed to hold small amounts of data that can fit entirely in memory. The name combines the Unix /etc directory, where a single machine keeps its configuration, with "d" for distributed: a distributed /etc for configuration that a whole cluster depends on.

The README lists four design goals: simple (a well-defined, user-facing gRPC API), secure (automatic TLS with optional client certificate authentication), fast (the README says it is benchmarked at 10,000 writes per second) and reliable (properly distributed using Raft). It is written in Go, licensed under Apache-2.0, and is best known as the store behind Kubernetes: the documentation explains that the Kubernetes API server persists cluster state into etcd and uses etcd's watch API to monitor the cluster and roll out configuration changes. The README also names locksmith, vulcand and Doorman among the applications it is frequently paired with, and points to an ADOPTERS file of production users.

It is aimed at platform and infrastructure engineers who need configuration management, service discovery, leader election or distributed locks with strong consistency, and at anyone operating Kubernetes control planes, where etcd health is cluster health.

How it works

etcd uses the Raft consensus algorithm to manage a highly available replicated log. Raft is leader-based: the leader handles every client request that needs cluster consensus, but clients do not need to know which member is the leader, because a follower automatically forwards such requests. Requests that do not need consensus, such as serialized reads, can be served by any member. A write is committed once a quorum of (n/2)+1 members agrees, which is why the documentation recommends odd cluster sizes and says a cluster should probably have no more than seven members; a five-member cluster tolerates two failures.

The data model is a multi-version persistent key-value store. The logical view is a flat binary key space with a lexically sorted index, so range queries are cheap. Every atomic change, including a multi-operation transaction, creates a new monotonically increasing revision, and previous versions of keys stay readable and watchable until the store is compacted. Physically, etcd keeps revision deltas in a persistent B+tree on disk, plus an in-memory B-tree index from user keys to revisions. That design is what makes watches with history ("time travel queries") and inexpensive snapshots possible.

Because disk latency is part of leader liveness, etcd is sensitive to slow storage. The FAQ is explicit that a leader waiting on a slow fsync is effectively unavailable, and that frequent leader loss usually means tuning disk settings or time parameters.

Key features

• gRPC API with a JSON gateway: the client protocol is gRPC, which can also be served as JSON over HTTP, so even curl can talk to it.
• Linearizable reads: the comparison table in the docs lists linearizable reads with a minimum latency of one network round trip.
• MVCC and revisions: every change gets a global revision number, useful for ordering and for fencing tokens.
• Watches: change notification over historical and current key intervals; the docs say watches never silently drop events.
• Transactions: compare-and-act transactions over fields, reads and writes.
• Leases, locks and elections: lease primitives with TTLs, plus lock and election RPCs and etcdctl commands for both.
• Role-based access control and TLS for securing clusters.
• Runtime reconfiguration: members can be added, removed or added as non-voting learners while the cluster runs, with strict-reconfig-check rejecting changes that would cause quorum loss.
• Snapshots: etcdctl provides a snapshot command for backups.

Getting started

The README recommends the pre-built release binaries for macOS, Linux, Windows and Docker on the GitHub releases page. If you installed them as described there, start a single-member cluster from the install location:

/tmp/etcd-download-test/etcd

Or move the binary onto your path and run it directly:

mv /tmp/etcd-download-test/etcd /usr/local/bin/
etcd

etcd now listens on port 2379 for client traffic and 2380 for peer traffic, the official IANA ports. Set and read a key with the bundled client:

etcdctl put mykey "this is awesome"
etcdctl get mykey

For a local three-member cluster, the repository ships a Procfile for goreman. After installing goreman, run:

goreman start

This starts members infra1, infra2 and infra3, with an optional gRPC proxy. Go applications add the v3 client with:

go get go.etcd.io/etcd/client/v3

The README links on to the operations guide for multi-machine clustering, configuration flags, TLS and tuning. Note that it warns the main branch may be unstable or even broken during development; use tagged releases.

Use cases

• Kubernetes control planes: storing cluster state for the API server, the best-documented deployment.
• Configuration management: a small, consistent source of truth for settings that many services watch for changes.
• Service discovery: registering instances under keys bound to leases, so entries disappear when a service stops renewing.
• Leader election and coordination: electing one active worker among replicas, or limiting how many nodes reboot at once, as CoreOS's locksmith did with a distributed semaphore over etcd.
• Ordering metadata: using revisions as fencing tokens when coordinating processes.

How it compares

The etcd documentation includes its own comparison and openly notes that it is written by the etcd team, whose biases favour etcd. Against ZooKeeper, it says etcd was informed by ZooKeeper's design and adds dynamic membership reconfiguration, an MVCC data model, reliable watches, lease primitives decoupled from sessions, and a gRPC protocol rather than ZooKeeper's custom Jute RPC. Against Consul, it frames the two as solving different problems: Consul is an end-to-end service discovery framework with health checks and DNS, while etcd is the better fit when what you need is a consistent key-value store. Against NewSQL databases such as CockroachDB, TiDB and Cloud Spanner, it says those shard data and scale to terabytes, whereas etcd keeps all data in a single replication group and is meant for metadata measured in gigabytes. The rule of thumb in the docs: choose etcd for metadata and coordination, and a NewSQL database if you need more than a few GB or full SQL.

Things to know before adopting

• Size limits: etcd enforces a storage quota of 2 GB by default; the FAQ suggests 8 GB as a maximum for normal environments and says the machine should have at least enough RAM to cover the quota.
• Compaction is your job: without periodic compaction (for example --auto-compaction) the history grows until a space alarm stops writes with mvcc: database space exceeded. Recovery is compact, defragment every endpoint, then disarm the alarm.
• Disks matter: SSDs are highly recommended. The FAQ suggests watching wal_fsync_duration_seconds (p99 under 10 ms) and backend_commit_duration_seconds (p99 under 25 ms).
• Membership changes need care: when replacing a failed member, remove it first and then add the replacement, to avoid permanent quorum loss.
• Locks are not magic: the docs explain that etcd's lock API relies on leases and revision checks, and cannot by itself protect resources outside etcd unless those resources also validate a version number.
• Cross-region clusters improve fault tolerance but add consensus latency and need heartbeat and election timeouts tuned.
• Platform: the docs call Linux on amd64 the most stable production environment.
• Licence: Apache-2.0.

Project activity

As of October 2026 the repository has about 52,400 stars and roughly 10,500 forks. It was created in July 2013, is written in Go, is licensed under Apache-2.0, and was pushed to in October 2026; the latest release at the time of writing is v3.7.3, published on 22 October 2026. The project holds weekly community and issue-triage meetings and discusses development in the #sig-etcd channel on the Kubernetes Slack. Documentation is at etcd.io/docs and the source is at github.com/etcd-io/etcd.