Cloud Parts

etcd

The Raft-replicated key-value store that holds every Kubernetes cluster’s state, built for small, critical data that many machines must agree on.

What it is
Coordination services,Key-value stores
Type
Open source
Made by
Cloud Native Computing Foundation
License
Apache 2.0
Facts checked
6 October 2026
Website Source code

What it is

etcd is a key-value store written in Go that runs as a cluster of usually three or five members. The members elect a leader with Raft. Every write goes to the leader, which replicates it to the others and applies it once a majority has it, so the cluster keeps working while any majority is up. Reads are linearizable by default: they too go through consensus and always return the latest committed value, unless a client opts into faster, possibly stale “serializable” reads. Keys live in one flat, sorted byte keyspace, so a prefix such as /registry/pods/ is a cheap range query, and clients talk to it over gRPC.

etcd keeps history. Every change creates a new cluster-wide revision and the old value stays readable until the history is compacted. A client can read the store as it was at a past revision, and a watch streams every change from a given revision onward, so a client that was disconnected resumes where it left off without missing events. Leases tie keys to a client’s keep-alives: when the lease expires, its keys are deleted. Transactions compare a key’s revision, version or value and then apply a set of writes atomically, and built-in lock and election APIs package the usual patterns.

Its best-known job is storing every object of a Kubernetes cluster, and managed Kubernetes services such as Amazon EKS run it for you. It is built for metadata, not bulk data: requests are capped at 1.5 MiB by default, the store at 2 GiB by default, with 8 GiB as the suggested maximum. etcd joined the CNCF in 2018 and graduated in November 2020; the current line is 3.7, released in July 2026.

Why teams pick it

  • Strong consistency by default, a simple model, and scrutiny to match: Jepsen tested it in 2020 and a Trail of Bits audit found no significant issues in its core
  • Watches that resume from a revision, so a client never silently misses a change
  • Leases, transactions and ready-made lock and election commands cover most coordination patterns
  • A gRPC API with clients in many languages; its Raft library also powers CockroachDB, TiDB and others

Watch out for

  • Small data only: 1.5 MiB per request, a 2 GiB default quota and 8 GiB suggested at most
  • Needs housekeeping: compact old revisions and defragment, or a full store raises an alarm and the cluster accepts only reads and deletes
  • Very sensitive to disk write latency and network round trips; slow disks or starved CPUs cause missed heartbeats, leader elections and instability
  • Every write goes through one leader, so more members add fault tolerance, not write throughput; the docs advise no more than seven

Alternatives

What all coordination services have in common →
Apache ZooKeeperOpen sourceThe coordination service from Yahoo that a generation of Hadoop-era systems use for leader election, membership and configuration.

How it fits with other technologies

Revisions, watches from the past, compare-and-swap and cluster status · bash

etcdctl put /config/mode blue
etcdctl put /config/mode green
etcdctl get /config/mode --rev=2              # read the value as of revision 2

# replay every change under /config/ since revision 2, then keep following
etcdctl watch /config/ --prefix --rev=2

# switch to red only if nobody changed the key since revision 3
etcdctl txn <<'EOF'
mod("/config/mode") = "3"

put /config/mode red

EOF

etcdctl compaction 3                          # drop history older than revision 3
etcdctl -w table endpoint --cluster status    # leader, Raft term and database size per member

See it in a real stack

No architecture uses etcd yet. Drop it into the playground and wire it up yourself.Open playground →
Where it came from2013–2026

In 2013 CoreOS was building a Linux distribution for clusters that updated itself automatically. That meant machines had to coordinate: share configuration, find each other’s services, and agree on who may reboot when, so a whole cluster never restarted at once. ZooKeeper solved similar problems, but CoreOS wanted something simpler to use. On July 23, 2013, Brandon Philips announced etcd: a key-value store written in Go, inspired by ZooKeeper and doozer, with an HTTP and JSON API you could use with curl, replicated with the then-new Raft consensus algorithm.

Kubernetes adopted etcd as the store for all of its cluster state, and that pushed etcd toward far larger loads than coordinating machine updates. Version 3.0, in June 2016, redesigned the API from that experience: gRPC instead of JSON, a flat keyspace with multiversion history and transactions, streaming watches, and leases in place of per-key expiry times. CoreOS said the goal was tens of thousands of active clients working on a million keys in one cluster.

etcd joined the Cloud Native Computing Foundation in December 2018 and graduated in November 2020, after Jepsen testing and a third-party security audit. With version 3.6 in May 2025, its first minor release in almost four years, the project also became a Kubernetes special interest group, sig-etcd.

Why it’s built this way

Raft and a curl-able API
CoreOS wanted a store that was simple to use and properly replicated. Raft gave a replicated log with a clear leader, and HTTP with JSON meant any script or language could talk to it without a special client.
Keep old versions of every key
With multiversion history, snapshots are cheap and a watch can start from a past revision, so a client that disconnects for a while resumes from the last event it saw instead of rereading everything.
Leases instead of a TTL on each key
In etcd2 every expiring key had to be refreshed through consensus, so an idle cluster still did a steady stream of writes. A lease is kept alive over one gRPC stream, handled by the leader without consensus, and many keys can share it.
gRPC instead of JSON
gRPC multiplexes many calls and watches over one HTTP/2 connection, and CoreOS measured a 2x edge in message processing over etcd2’s optimised JSON. A gateway still serves JSON for simple clients.

Timeline

  1. 2013

    CoreOS announces etcd on July 23

  2. 2015

    etcd 2.0, the first major stable release, in January

  3. 2016

    etcd 3.0 brings the gRPC API, multiversion history and leases

  4. 2018

    Joins the CNCF as an incubating project in December

  5. 2020

    Graduates in the CNCF in November

  6. 2025

    etcd 3.6 in May; the project becomes Kubernetes’ sig-etcd

  7. 2026

    etcd 3.7 in July

Sources19 · facts checked 6 October 2026

Improve this page on GitHub