# Consensus and Raft

> How a majority of nodes agree on one ordered log, and why you rent this from etcd or ZooKeeper.

Concept · Consistency & coordination · https://levelcode.org/concepts/consensus-raft

Consensus lets a group of nodes agree on a sequence of values — a replicated log — even when some nodes crash and messages are delayed or lost. It underpins leader election, distributed locks, configuration stores and strongly consistent databases. Raft and the Paxos family are the standard algorithms.

## Raft in outline

- **Terms and leaders.** Time is divided into numbered terms. In each term, at most one leader is elected; a candidate needs votes from a **majority** of nodes, and each node votes once per term.
- **Log replication.** Clients send commands to the leader. It appends them to its log and replicates them to followers.
- **Commit.** An entry is committed once stored on a majority. Committed entries are never lost: any future leader must win a majority vote, every majority overlaps the majority that stored the entry, and voters refuse candidates whose logs are less up to date.
- **Failover.** If followers stop hearing from the leader, they time out, start a new term and elect a new leader.

## The numbers

A cluster of **2f + 1** nodes tolerates **f** failures:

| Nodes | Majority | Tolerates |
|---|---|---|
| 3 | 2 | 1 failure |
| 4 | 3 | 1 failure |
| 5 | 3 | 2 failures |
| 7 | 4 | 3 failures |

Even sizes add cost without adding tolerance, so clusters are 3 or 5 nodes (occasionally 7).

## The costs

- Every write needs a round trip to a majority; across regions, that's the inter-region latency on every commit.
- Throughput is thousands to tens of thousands of writes per second, not millions, because everything flows through one leader.
- The minority side of a partition can't make progress — consensus systems are CP ([CAP theorem](https://levelcode.org/concepts/cap-theorem)).

## Rent, don't build

Correct consensus implementations took years of testing. Use **etcd**, **ZooKeeper** or **Consul** for small, critical, strongly consistent data — leader leases, configuration, service discovery, shard maps — or a database built on consensus (CockroachDB, TiDB, Spanner, YugabyteDB). Don't use a coordination store as a general database: keep its data small and its write rate modest.

See [leader election](https://levelcode.org/concepts/leader-election), [leases and fencing tokens](https://levelcode.org/concepts/leases-and-fencing-tokens) and [quorums](https://levelcode.org/concepts/quorums).