How does leader election work in KRaft, and what is a leader epoch?

## Key vocabulary - **Voter**: a controller node that can vote and be elected. - **Epoch (a.k.a. term in classic Raft)**: a monotonically increasing integer that labels each leadership period. Every record in the log and many RPCs carry the epoch of the leader that produced/sent them. - **Candidate**: a voter currently trying to get elected. - **Election timeout**: a randomized timer; if a voter hears nothing from a valid leader before it fires, it starts an election. ## The election sequence 1. **Trigger**: A voter's election timeout fires (it has not received a valid Fetch response/heartbeat from the current leader, or it just started up with no leader). 2. **Become candidate**: It increments the epoch to `currentEpoch + 1`, votes for itself, and persists its vote (so it cannot vote twice in the same epoch even after a crash). 3. **Request votes**: It sends a **Vote** RPC to every other voter, including its `lastOffset` and `lastEpoch` (the offset/epoch of the final record in its own log). 4. **Granting a vote**: A peer grants the vote only if BOTH: (a) the candidate's epoch is not older than the peer's, and (b) the candidate's log is **at least as up-to-date** — its `lastEpoch` is higher, or equal-and-its `lastOffset >= peer's`. The peer records that it voted in this epoch so it won't vote again. 5. **Win**: With votes from a **strict majority** of voters (e.g., 2 of 3), the candidate becomes **leader** for that epoch. 6. **Announce**: The new leader sends **BeginQuorumEpoch** to the other voters so they recognize it and start fetching from it. ## Why the up-to-date-log rule matters This rule is the heart of Raft's safety: a candidate can only win if it already holds every **committed** record. Because a committed record lives on a majority, and a winning candidate needs a majority's votes, those two majorities overlap in at least one voter — guaranteeing the new leader is not missing committed data. This is the **Election Safety / Leader Completeness** property. ## Split votes and liveness If two candidates start simultaneously, votes can split with no majority. Each voter votes at most once per epoch, so neither wins; timeouts fire again, the epoch bumps, and a fresh round runs. **Randomized** timeouts make simultaneous candidacies unlikely, so the cluster converges quickly in practice. ## KRaft-specific details - KRaft adds a **Pre-Vote / pre-candidate** style check (and a leader-fencing mechanism) to avoid disruptions from a partitioned node that keeps bumping the epoch — a node checks it could win before actually incrementing the epoch and forcing a new election. - Epochs also appear in **Fetch** responses; a follower learns about a newer epoch and steps down/re-routes accordingly. - A node that sees a higher epoch than its own always steps down to follower and adopts that epoch. ## Common pitfalls - Thinking the highest broker id or lowest node id wins — election is by majority vote constrained by log freshness, not by id. - Forgetting that votes are persisted, so a crashed-and-restarted voter still honors its earlier vote in that epoch.