《Kubernetes 分布式系统原理深入解析》4.2 Leader Election 客户端库原理

K8s 把选主逻辑封装成客户端库 leaderelection,组件只需提供 Lease 名称、候选者身份与『成为/失去领导权』回调。本节拆解库的状态机:TryAcquire 尝试夺取、Renew 续约、ObservedRecord 记录最新 holder、LeaderCallbacks 回调触发,以及防双主的乐观锁保障。lab 用 leaderelection/le.go 验证库的三态流程。

4.2 Leader Election 客户端库原理

上一节讲了 Lease 对象;本节讲谁在操作它。K8s 把选主逻辑封装成一个客户端库(client-go/leaderelection),组件本身几乎不用写任何选主代码。理解这个库的状态机,就能理解 controller-manager / scheduler 的「单活」是如何自动化实现的。

库的接口:组件只需三样东西

组件使用 leaderelection 库时只需提供:

  1. Lock:要争的锁(LeaseLock,指向某个 Lease 对象)。
  2. Identity:本副本的身份(如 hostname+进程 ID)。
  3. 回调: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 章),双主不会造成数据损坏,只可能造成重复动作。

故障转移:库视角

一次完整故障转移:

  1. leader(host-1)进程崩溃,停止续约。
  2. Lease.renewTime 停在崩溃时刻。
  3. 超过 leaseDuration(15s)后租约过期。
  4. host-2 的下一个 TryAcquire 周期发现过期,接管。
  5. 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「只接管过期租约」的语义验证。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图