4.2 Leader Election 客户端库原理
上一节讲了 Lease 对象;本节讲谁在操作它。K8s 把选主逻辑封装成一个客户端库(client-go/leaderelection),组件本身几乎不用写任何选主代码。理解这个库的状态机,就能理解 controller-manager / scheduler 的「单活」是如何自动化实现的。
库的接口:组件只需三样东西
组件使用 leaderelection 库时只需提供:
- Lock:要争的锁(LeaseLock,指向某个 Lease 对象)。
- Identity:本副本的身份(如 hostname+进程 ID)。
- 回调:
OnStartedLeading(成为 leader 时)、OnStoppedLeading(失去 leader 时)。
组件逻辑(控制器主循环、调度循环)放在 OnStartedLeading 里。库保证:只有 leader 会运行你的主循环。
状态机:三种状态
选主库是一个三态循环:
Idle(未持锁)
│ TryAcquire 成功
▼
Leading(持锁)
│ Renew 续约 / Renew 失败达上限
▼
Stopped(主动退出或失去锁)
每个周期(默认 2s)执行:
- If leader:Renew——刷新 Lease 的 renewTime。
- If not leader:TryAcquire——若租约过期则接管。
库还维护一个 ObservedRecord:最近观察到的 holder 与租约状态。它让组件可以回答「现在谁是 leader、租约还多久到期」,而不用直接操作对象。
TryAcquire:夺取协议
TryAcquire 的完整逻辑:
读 Lease 当前状态
if 租约存在 且 未过期(renewTime+duration > now):
return 未夺得(等下一个周期)
else:
// 空租约 或 已过期
if 上次观察到的 holder 仍有效:
记录一次 leader 变更(OldLeaderObserved)
写 Lease:holderIdentity=self, acquireTime=now, renewTime=now
leaseTransitions++
return 夺得
关键设计:接管前必须确认「旧 holder 确实失效」。库记录观察到的旧 holder 与租约状态,若旧 holder 还在续约(未过期),就不会夺。这避免了「两个 leader 并存」的最坏情况。
Renew:续约协议
Renew 的完整逻辑:
读 Lease(带乐观锁,RV)
if 当前 holder == self:
写 Lease:renewTime = now
else:
// 锁被别人抢了(本应不会,但防意外)
return 续约失败,进入 Stopped
续约用 apiserver 的 Update 携带 RV。两个副本若同时试图续约同一个 Lease,乐观锁保证只有一个成功——这从存储层杜绝了双主。
若续约连续失败(如 apiserver 不可达)达到 renewDeadline(默认 10s),库放弃领导权,执行 OnStoppedLeading 并退出主循环。
防双主:多层保障
「同一时刻只有一个 leader」由多层机制保证:
| 层 | 机制 |
|---|---|
| 存储层 | Lease 写带 RV 乐观锁,并发写只有一个成功 |
| 库层 | TryAcquire 只接管过期租约;Renew 只认自己是 holder |
| 应用层 | 只有 OnStartedLeading 里的主循环会动作 |
即使有极端时序(网络分区 + 时钟漂移),这些层叠加起来把双主窗口压到极小。真实 controller-manager 因此可以在「最坏情况」下偶发短暂双主,但因为控制器动作幂等(卷二第 6 章),双主不会造成数据损坏,只可能造成重复动作。
故障转移:库视角
一次完整故障转移:
- leader(host-1)进程崩溃,停止续约。
- Lease.renewTime 停在崩溃时刻。
- 超过 leaseDuration(15s)后租约过期。
- host-2 的下一个 TryAcquire 周期发现过期,接管。
- host-2 的 OnStartedLeading 触发,启动主循环。
从崩溃到接管 ≈ leaseDuration + 库周期(15~17s)。这就是为什么 controller-manager 故障转移不是瞬时:它取决于租约过期时长。
RenewDeadline 与 ReleaseOnCancel:库的退出路径
选主库有两个「退出」机制,理解它们才能解释「leader 怎么把位置让出来」:
RenewDeadline:连续续约失败的硬上限(默认 10s)。leader 在 10s 内无法成功续约(apiserver 不可达、网络分区),库主动放弃领导权,执行 OnStoppedLeading。
每个周期:Renew
├─ 成功 → 重置失败计数
└─ 失败 → 失败计数++
└─ 连续失败 ≥ 10s → 放弃领导权,调用 OnStoppedLeading
放弃后主循环停止。租约在过期后由其他候选者接管——leader 不是「恢复后抢回」的,除非它在租约过期前成功续约。
ReleaseOnCancel:进程收到取消信号(优雅退出)时,库主动清空 Lease 的 holderIdentity(设为空),让接管立即发生而不必等过期。这避免了「leader 优雅下线还要等 leaseDuration」的延迟。
对比三条退出路径:
| 退出方式 | 时机 | 租约状态 | 接管等待 |
|---|---|---|---|
| 优雅退出(ReleaseOnCancel) | 收到信号 | 立即清空 holder | 下一周期 |
| 崩溃 | 无信号 | renewTime 停在崩溃点 | 等过期 |
| 续约失败(RenewDeadline) | 连续失败 10s | 停止续约 | 等过期 |
工程意义:优雅退出可以加速故障转移,崩溃只能靠租约过期。这也是为什么滚动重启 controller-manager 时选主切换很快——新版本进程优雅退出时主动释放了租约。
identity 的唯一性:为什么它要足够独特
holderIdentity 默认是 hostname_uuid(或类似组合)。它必须唯一,因为:
- 接管判定依赖「旧 holder 是不是我」:若两个副本 identity 相同,Renew 时「holder == self」会误判,可能两个都以为自己是 leader。
- 审计依赖 identity 区分「谁当过 leader」。
身份唯一是选主正确性的隐含前提——「我是唯一」必须在 identity 上成立,乐观锁才防得住双主。反过来,identity 也不该频繁变化(每次重启都要变身份),否则无法追踪「同一进程的连续领导任期」——所以它取 hostname + 进程标识的组合,进程重启身份即变,正是为了区分「同主机的新进程」。
三个常见误解
- 「选主库 = Lease 资源」——错误。库是代码,Lease 是数据。库读写 Lease 实现选主。
- 「成为 leader 是即时的」——错误。TryAcquire 只在一个周期检查一次,且只在租约过期后接管;故障转移要等 leaseDuration。
- 「双主不可能发生」——工程上被压到极小但非零(时钟漂移 + 分区)。它不危险,因为控制器幂等。
leader-elect:一个反复出现的命令行参数
controller-manager 和 scheduler 都接受 --leader-elect=true 参数。它不是一个「开关」那么简单,背后是选主库的完整装配:
--leader-elect-resource-name:Lease 名称(默认kube-controller-manager)。--leader-elect-lease-duration/--renew-deadline/--retry-period:租约时长、放弃阈值、循环周期。--leader-elect-resource-namespace:Lease 所在命名空间。
这些参数把 4.2 节的库状态机「暴露」成可配置项。运维调优的杠杆全在这里:想让接管更快就调短 lease-duration(但提高易手率),想让选主更稳就调长。理解库的状态机,这些参数就不再是魔法——它们对应的是 TryAcquire 的过期窗口、Renew 的失败阈值和循环周期。
本节 lab
本节验证选主库的三态核心:无租约可夺取、有租约不可抢、接管不踩活租约:
cd private/labs/k8s-ctrl-lab
go test ./leaderelection -run 'TestAcquireThenExpire' -v
TestAcquireThenExpire 覆盖库的完整状态流:a 夺取空租约 → b 在有效期内 TryAcquire 失败 → 租约过期后 b 接管 → 领导权移交。这正是 TryAcquire「只接管过期租约」的语义验证。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。