# etcd: A Raft-Backed Key-Value Store — Distributed Systems & Consensus (Raft / Paxos)

Source: https://www.skillbyai.com/en/distributed-consensus/dc-etcd

> Use etcd's keys, revisions, transactions, leases and watches, and explain why Kubernetes stores its state there.

## What etcd gives you

**etcd** is a distributed key-value store that replicates its data with Raft, and it is the store behind the Kubernetes API server. Every change gets a cluster-wide, monotonically increasing **revision**, so you can read a key as of an old revision or watch for changes after one. Its main primitives are: **put/get/delete** on keys and prefixes; **transactions** (`txn`) that atomically compare a key's value, version or revision and then run one set of operations or another, which is how you build compare-and-swap; **leases**, time-to-live grants that keys can be attached to so they vanish when a client stops renewing (keep-alive); and **watches**, streams of events for a key or prefix. Because all of this sits on a Raft log, every write costs a quorum round trip and an fsync. etcd is therefore designed for small amounts of critical coordination data (configuration, service discovery, leader election), not as a general-purpose bulk database.

## Consensus in real systems

etcd exposes Raft as keys, leases and watches; ZooKeeper offers znodes and sessions on Zab; applications build locks and leader election on top, protected by fencing tokens.

![Three stages: etcd, ZooKeeper, and application-level locks with fencing tokens.](assets/figures/distributed-consensus/section-9-map.svg) — Figure 9.1: etcd (Raft) -> ZooKeeper (Zab) -> locks and fencing tokens

## Leases, transactions and watches with etcdctl

A key attached to a 30-second lease disappears unless kept alive. The transaction creates `/leader` only if it does not exist yet (create revision 0), which is the core of a simple election. `etcdctl txn` reads the compare, success and failure blocks from standard input, separated by blank lines.

```bash
# Grant a lease and attach a key to it (prints the lease ID)
etcdctl lease grant 30
etcdctl put /services/api/node1 10.0.0.5:8080 --lease=<lease-id>
etcdctl lease keep-alive <lease-id>

# Atomic create-if-absent with a transaction
etcdctl txn <<'TXN'
create("/leader") = "0"

put /leader node1

get /leader

TXN

# Stream every change under a prefix
etcdctl watch --prefix /services/
```

## Keep etcd small and fast

etcd is sensitive to disk fsync latency and network latency between members. Put it on fast local SSDs, keep members in one region or nearby zones, and do not store large blobs in it: it enforces a request size limit and a total database quota.

**Quiz:** Which etcd feature lets a key disappear automatically when its owner stops responding?

- [ ] Watches
- [ ] Revisions
- [x] Leases
- [ ] Compaction

*Answer:* Leases. Keys attached to a lease are deleted when the lease expires, which happens when the client stops sending keep-alives.