From b04de8ba75ec2268cdcf4a0903154ef32216737f Mon Sep 17 00:00:00 2001 From: Sohan Dhanak Date: Mon, 15 Dec 2025 13:52:49 +0000 Subject: [PATCH] docs: Introduce a glossary for Raft --- doc/raft.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/doc/raft.md b/doc/raft.md index b0a29fdbbc..6a96d84462 100644 --- a/doc/raft.md +++ b/doc/raft.md @@ -227,6 +227,58 @@ sequenceDiagram end ``` +## Glossary + +**Leader** - The replica in a Raft group that handles all write operations and coordinates log replication to followers. Only one leader exists per term per Raft group. + +**Follower** - A replica that replicates log entries from the leader. Followers transition to candidates if they don't receive heartbeats from the leader within the election timeout. + +**Candidate** - A follower that initiates an election to become the new leader when it hasn't received heartbeats within the election timeout. Only a voter can become a candidate. + +**Voter** - A replica that participates in elections and contributes to quorum. Standard voting member of the Raft group. + +**Learner** - A non-voting replica that receives log entries but doesn't participate in elections or quorum. Used to bring new replicas up to speed before promoting them to voters. + +**Term** - A logical clock value that increases monotonically. Each term has at most one leader. Used to detect stale information. + +**Index** - The position of a log entry in the Raft log, equivalent to the LSN (Log Sequence Number) in Gitaly. The index is a monotonically increasing integer that uniquely identifies each entry's position within a partition's log. Combined with the term, it provides a complete identifier for log entries and is used to track replication progress, determine commit points, and maintain consistency across replicas. + +**Election** - The process by which a new leader is chosen when the current leader fails or during initial cluster bootstrap. + +**Quorum** - The majority of replicas (⌊n/2⌋ + 1) required to commit a log entry. For a 3-replica Raft group, quorum is 2 replicas. + +**Partition** - A collection of related repositories that share the same Write-Ahead Log (WAL) and are managed by a single Raft group. May contain a single repository or related repositories (e.g., fork networks). + +**PartitionKey** - A globally unique identifier for a partition, generated as a SHA256 hash of `(Authority Name, Local Partition ID)`. Remains constant throughout the partition's lifecycle. + +**Authority Name** - The storage that originally created a partition. Part of the PartitionKey generation. + +**Storage** - A named location where partitions are hosted. A Gitaly server can host multiple storages simultaneously. + +**Replica** - An instance of a partition on a specific storage. Identified by `(PartitionKey, Member ID, Storage Name)`. + +**LSN (Log Sequence Number)** - A monotonic sequence number for log entries within a partition. All repositories in a partition share the same LSN space. + +**Member ID** - An integer identifier assigned to a Raft group member by etcd/raft. For the initial bootstrap member, this is always 1. For new members, it's assigned as the LSN of the configuration change entry. + +**Replica ID** - Complete identifier for a replica consisting of `(PartitionKey, Member ID, Storage Name)`. + +**Raft Group** - A set of replicas that participate in consensus for a specific partition. Each partition has its own independent Raft group. + +**WAL (Write-Ahead Log)** - A persistent log of all operations performed on a partition. Entries are written to WAL before being applied to the repository state. + +**Replication Factor** - The number of replicas maintained for a partition. + +**Routing Table** - A globally distributed, eventually consistent table mapping PartitionKeys to their replica locations and metadata. + +**Heartbeat** - Periodic messages sent by the leader to followers to maintain authority and prevent elections. + +**Snapshot** - A point-in-time copy of a partition's state, used to bring new or lagging replicas up to date without replaying the entire log. + +**Cluster ID** - Identifier for the entire Gitaly Raft cluster, used to prevent cross-cluster communication. + +**Node** - A Gitaly server instance that can host multiple storages and participate in multiple Raft groups. + ## References - [Raft-based decentralized architecture for Gitaly Cluster](https://gitlab.com/groups/gitlab-org/-/epics/8903) -- GitLab