← Back to blogs

WTH is Raft?

Raft is the consensus algorithm that keeps a replicated log identical across a cluster even when servers crash, messages are lost, and the network partitions. It is the "how" behind the CAP/PACELC choice to be CP: a protocol that guarantees one leader, one committed log, and no two servers that disagree on what was committed.

1. What Raft Actually Solves

Raft solves consensus for a replicated state machine: a set of servers agree on an ordered log of commands, each server applies the log to its local state machine, and the result is that all non-faulty servers end up in the same state. It does not magically make all servers' state consistent at every instant — it makes the committed prefix of the log identical, which is the precise guarantee a CP system needs.

• Consensus, not a lock service. Raft agrees on what to apply, in order. A distributed lock is a trivial command on top of that log, but Raft itself is not a lock service.
• Replicated log, not replicated database. Raft replicates an ordered command log. Whether that log encodes SQL, key-value writes, or membership metadata is up to the application.
• Linearizable agreement. Once a command is committed, every future read from any server observes it, and committed commands appear in the same order to every server.

The key design decision Raft makes is leader-based consensus: rather than letting every server propose arbitrary commands (as Paxos does), Raft elects a single leader who owns all client writes. That makes the protocol dramatically easier to reason about and implement correctly, at the cost of routing every write through one node.

2. The Cluster Model: Leader, Followers, and the Log

Every server is in exactly one of three roles at any moment:

• Leader: receives all client commands, appends them to its log, replicates them, and tells followers what is safe to commit. There is at most one leader per term.
• Follower: passively receives AppendEntries (heartbeats carrying log entries) from the leader and votes when an election is called.
• Candidate: a follower whose election timer expired; it increments the term and asks the cluster for votes.

The log is the spine of everything. Each log entry holds the client command plus the term in which it was appended. The term is a monotonically increasing integer — the cluster's logical clock. Matching a leader's log entry (same index, same term) is what lets Raft prove that two servers agree.

3. Terms and Leader Election

Time in Raft is divided into terms. A term starts with an election; if a candidate wins, it serves as leader for the rest of the term. A term can also end with no leader (a split vote), and the next term starts immediately. Servers persist the current term and never accept a message with a stale term.

Every follower runs an election timer with a randomized timeout (typically 150–300 ms). When the timer expires without hearing from the current leader, the follower becomes a candidate, increments the term, votes for itself, and sends RequestVote to every other server. A server grants its vote only if:

• the candidate's term is at least as new as its own, and
• the candidate's log is at least as up to date as its own (a longer log, or an equal-length log with a newer last term).

A candidate becomes leader when it receives votes from a majority of the cluster (⌊N/2⌋ + 1). Because the randomized timeout makes simultaneous candidacies rare, and because a majority vote is impossible for two competing candidates in the same term, the election reliably settles on one leader. If the vote splits, everyone times out again and a new term begins.

4. Log Replication and Commit

Once elected, the leader begins sending AppendEntries to followers — empty entries as heartbeats, and real entries when clients submit commands. Followers append entries to their own logs and ack. The leader tracks, per follower, the highest log index it knows is replicated.

Two mechanisms make this safe:

• Log matching property. When a leader sends an entry at index i, it includes the term and index of the entry before it. A follower rejects the append unless its log already matches that previous entry. This guarantees two logs with identical (index, term) entries are identical all the way back — no divergent histories can hide in the past.
• Commit on majority. An entry is committed once a majority of servers have appended it. The leader then advances its commit index and tells followers via the next heartbeat. Only committed entries are applied to the state machine.

Raft never commits an entry from a previous term just because a later entry from the current term is committed — the classic trap that breaks Paxos implementations. The leader only commits its own current-term entries directly; previous-term entries become committed transitively once a current-term entry covers them.

5. Why Raft Is Safe

The safety argument is a majority-overlap argument, and it is worth stating precisely:

• Leader completeness. Any entry committed in term T is present on a majority of servers. The next leader in any later term must receive votes from a majority, and those two majorities must intersect — so the new leader's log contains every committed entry from term T.
• Log matching prevents divergence. Because followers only accept appends that match the preceding entry, no two logs can commit different values at the same index.
• Single leader per term. A majority is required to elect a leader, and two majorities in the same term cannot both elect different leaders. A leader that is partitioned away from a majority cannot commit anything, and a leader that comes back with a stale log is quickly corrected by the current term's leader.

These three facts together rule out the two failures that matter: two leaders committing different logs, and a committed entry being lost after a leader change.

6. Log Compaction and Snapshots

A log that grows forever is a memory leak with a disk attached. Raft compacts the log by taking a snapshot: the state machine's current state plus the last included log index and term. Once a snapshot is persisted, all log entries before it can be discarded.

When a follower is far behind — new node, or a node that was offline through a snapshot — the leader sends InstallSnapshot instead of replaying every entry. The follower applies the snapshot and replaces its log prefix. This is where membership and snapshot coordination get operationally hairy: snapshot frequency is a disk-versus-recovery-time trade, and snapshotting too aggressively can starve new followers of log-based catch-up.

7. Membership Changes Without Losing Safety

Adding or removing a server while the cluster is running is the easiest way to break a consensus system. The danger: if you change membership in one shot, you can momentarily have two disjoint majorities — an old configuration and a new one — that elect two different leaders.

Raft handles this with the joint consensus approach: the new configuration is appended to the log as a special entry, and during the transition the cluster requires a majority of the old configuration and a majority of the new configuration. Only after the joint-consensus entry is committed does the cluster move to the new configuration alone. In practice, run exactly one membership change at a time, and never change quorum size while availability is already degraded.

8. Interactive 5-node Raft Cluster

The rules above are easy to read and easy to hand-wave. This simulator makes them visible. Watch what happens to the majority when you partition the network, and notice that the minority side can never elect a leader or commit an entry.

Key behaviors to try:

• Append entry with the network healthy: the entry reaches all 5 nodes and commits immediately (3 of 5 is a majority).
• Partition network then append: the leader's side reaches 3 nodes and still commits; the minority of 2 can never commit.
• Trigger election while partitioned: the majority side elects a new leader; the minority side's election fails for lack of a quorum.
• Crash the leader and trigger an election: a new leader is elected from the remaining nodes and the cluster keeps serving.

9. Raft in Real Systems

Raft is the engine inside some of the most widely deployed CP systems. Knowing which is which changes how you debug them:

• etcd: the reference Raft implementation powering Kubernetes. Every etcd write is a Raft round trip to a quorum of the etcd members — your Kubernetes write latency is a quorum latency.
• Consul: uses Raft for service discovery and the key-value store backing its catalog. The consensus group is small; the data plane (service mesh) is separate.
• CockroachDB: partitions the keyspace into ranges, each range replicated with Raft. Every SQL write to a range is a Raft commit across that range's replicas.
• TiKV: the distributed transactional KV store behind TiDB, replicating each region with Raft, and using a Raft-based PD cluster for placement metadata.
• Kafka KRaft: replaces ZooKeeper with a Raft-based metadata quorum. The metadata log is Raft-replicated; the data log (partitions) is not.

10. Failure Modes That Matter in Production

• fsync latency. Raft commits only after followers fsync their append to stable storage. Slow disks or a shared filesystem that lies about fsync will inflate p99 and stall commits.
• Tail latency under load. A leader that takes too long to respond looks dead to followers, whose randomized timers expire and trigger an election. A churning leader is a cluster that never commits.
• Minority partition. The side with fewer than a majority keeps "running" but cannot commit or elect. Client reads from that side are serving stale data unless reads are linearizable through the leader.
• Stale leader recovery. A partitioned leader comes back and is immediately stepped down when it sees a newer term. Without proper handling, clients that cached the old leader get rejected — that is expected, not a bug.
• Disk failure. A dead disk on a follower is fine (it is just one vote); on the leader it forces an election. A dead disk on the log device that is not detected is the dangerous one.
• Leader hot spot. All reads and writes flow through one node. It is the cluster's bottleneck by design, not a misconfiguration.

11. When Raft Is the Wrong Tool

• High-fanout shared-nothing stores. If every node is independent and does not need to agree on shared state, Raft is pure overhead.
• Strongly local workloads. A workload that reads and writes one region or one shard with no cross-node coordination does not need consensus — it needs replication plus an application policy.
• Eventual consistency at low latency. Dynamo-style quorum reads/writes or CRDTs get you availability without a leader and without a single committed log. That is a different, cheaper guarantee.
• Read-heavy metadata with tolerant reads. If stale reads are acceptable and writes are rare, a quorum scheme with async replication is cheaper than a full Raft commit on every write.

12. Key Takeaways

• Raft is consensus via a single leader: one leader per term, a replicated log, and commit only on a majority.
• Safety comes from three properties: leader completeness, log matching, and single-leader-per-term — all consequences of majority overlap.
• The randomized election timeout is what makes elections reliable; a split vote just starts a new term.
• Never commit an entry from a previous term directly; commit only current-term entries.
• Membership changes need joint consensus or a careful one-at-a-time approach, or you can create two disjoint majorities.
• Operationally, Raft is a quorum-latency system: fsync, tail latency, and leader hot spots are structural, not bugs.

Raft gives the cluster a single authoritative log. But not every system needs that — many need to contact a subset of replicas and tolerate partial answers. That is the next primitive: quorum reads and writes, where W + R > N decides how much consistency you get for how much availability.