docs/proposal/001-leader-election.md
---
title: leader election proposal
version: 0.15.1
authors: @ivankatliarchuk
creation-date: 2025-01-30
status: not-planned
---
In Kubernetes, leader election is a mechanism used by applications, controllers, or distributed systems to designate one instance or node as the "leader" that is responsible for managing specific tasks, while others operate as followers or standbys. This ensures coordinated and fault-tolerant operations in highly available systems.
The leader election mechanism implemented in Go code relies on Kubernetes coordination features, specifically Lease object in the coordination.k8s.io API Group. Lease locks provide a way to acquire a lease on a shared resource, which can be used to determine the leader among a group of nodes.
Leader Election Sequence Diagram
sequenceDiagram
participant R1 as Replica 1 (Leader)
participant LR as Lock Resource
participant R2 as Replica 2 (Standby)
participant R3 as Replica 3 (Standby)
R1->>LR: Update Lock Resource
Note over LR: currentLeader: R1
timeStamp: 12:21
leaseDuration: 10s
loop Every polling period
R2->>LR: Poll leader status
LR-->>R2: Return lock info
R3->>LR: Poll leader status
LR-->>R3: Return lock info
end
Note over R2,R3: Replicas remain on standby
as long as leader is active
Leader Election Flow
graph TD
subgraph Active Replica
A[Replica 1]
end
subgraph Kubernetes Resource Lock
A["fa:fa-server Replica 1"] --> |Hold The Lock| C@{ label: "Lock" }
end
subgraph Standby Replicas
D["fa:fa-server Replica 2"] -->|Poll| C
E["fa:fa-server Replica 3"] -->|Poll| C["fa:fa-lock Lock"]
end
style C color:#8C52FF,fill:#A6A6A6
style A color:#8C52FF,fill:#00BF63
style D color:#000000,fill:#FFDE59
style E color:#000000,fill:#FFDE59
How Leader Is Elected
flowchart TD
A[Start Leader Election] -->|Replica 1 Becomes Leader| B(Update Lock Resource)
B --> C{Is Leader Active?}
C -->|Yes| D[Replicas 2 & 3 Poll Leader Status]
C -->|No| E[Trigger New Election]
E -->|New Leader Found| F[Replica X Becomes Leader]
E -->|No Leader| G[Retry Election]
F --> B
G --> C
D --> C
Minimum supported Kubernetes version is v1.26.
Currently, this feature is "opt-in". The
--enable-leader-electionflag must be explicitly provided to activate it in the service.
| Flag | Description |
|---|---|
--enable-leader-election | This flag is required to enable leader election logic |
args:
--registry=txt \
--source=fake \
--enable-leader-election
Lease API:
Lease object in the coordination.k8s.io/v1 API group, specifically designed for leader election.Election Process:
Heartbeat (Lease Renewal):
Leader election ensures that:
Leader election functionality is critical for building reliable, fault-tolerant, and scalable applications on Kubernetes.