Documentation
¶
Overview ¶
Package leaderelection 提供基于 Kubernetes Lease 的选主简化封装: 一个二进制多副本部署时单活运行(定时任务分片、controller、缓存刷新等 场景的兜底互斥),底层即 kube-controller-manager 同款 leader election 协议(coordination.k8s.io/lease),对 apiserver 仅有 Lease 的 get/create/update 权限要求。
快速接入 ¶
cs, _ := k8s.NewClientset(k8s.Config{})
err := leaderelection.Run(ctx, cs, leaderelection.Config{
LeaseName: "my-app",
OnStartedLeading: func(ctx context.Context) {
// 当选:阻塞跑单活逻辑,直至 ctx 在失去领导权时被取消
serve(ctx)
},
OnStoppedLeading: func() {}, // client-go 要求非 nil;退出原因用 Run 返回值区分
})
// 退出原因用 Run 返回值区分,勿在 OnStoppedLeading 里无条件 log.Fatal:
// 失权(续约失败放弃领导权)返回 ErrLostLeadership——此时才退出交由重启
// (含续约失败与取消同窗:失权优先上抛,不被掩蔽成 ctx.Err(),#81);
// ctx 取消返回 ctx.Err()——优雅关停(含从未当选的副本,多副本部署里
// 它们是多数),正常退出即可;否则每次发布/缩容所有副本都以非零码
// 退出,把真实失权告警淹没。
if errors.Is(err, leaderelection.ErrLostLeadership) {
log.Fatal("lost leadership, exiting for restart")
}
Namespace 默认取 POD_NAMESPACE 环境变量,再回退 "default"; Identity 默认取「hostname_pid_随机后缀」(进程唯一,#100)——hostname 是主机级标识,同主机两进程 / 同 Pod 两容器会互认身份、双双当选,打破 兜底互斥;Deployment/StatefulSet 建议显式传 Pod 名。
Run 返回后应尽快退出进程,不要复用同一进程以同一 Identity 再入选举 (重新参与选主在语义上等同于未退出,等于主动放弃提前释放的价值)。
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrLostLeadership = errors.New("k8s leaderelection: lost leadership")
ErrLostLeadership 表示 elector 因失去领导权(续约窗口内续约失败)而退出。 失权意味着本副本已不适合继续单活职责,典型处理是进程退出交由重启, 而非把该错误当成功吞掉。
Functions ¶
func Run ¶
Run 参与选主并阻塞:当选后 OnStartedLeading 在独立 goroutine 中运行; 失去领导权或 ctx 取消时返回,退出原因通过返回值上抛——失权退出(续约 失败放弃领导权)返回 ErrLostLeadership,ctx 取消返回 ctx.Err()(含从未 当选就因取消退出的场景)。失权与 ctx 取消并存时失权优先(真实失败优先 于取消副作用,workflow#61 分类口径,#81):续约失败与取消同窗(续约 已在失败、RenewDeadline 窗口内触发关停)按失权上抛,ctx 取消信息仅留 在报文,errors.Is(err, context.Canceled) 不成立——失权副本不得被消费方 按「优雅关停」零退出吞掉告警。OnStoppedLeading 是「elector 退出」回调 (client-go 无条件触发,不区分失权/关停,见 Config.OnStoppedLeading), 先于返回触发;退出原因以 Run 的返回值为准。Run 内部已管理 goroutine, 禁止裸并发调用同一 elector。
Types ¶
type Config ¶
type Config struct {
// LeaseName 必填:Lease 资源名,同一 LeaseName 的副本参与同一场选主。
LeaseName string
// Namespace 是 Lease 所在命名空间(默认 POD_NAMESPACE 环境变量 → "default")。
Namespace string
// Identity 是候选人标识(默认「hostname_pid_随机后缀」,进程唯一,#100;
// Deployment/StatefulSet 场景建议显式传 Pod 名——可读且有稳定的语义
// 归属;同主机多进程 / 同 Pod 多容器场景**必须**用默认值或自行保证
// 进程唯一,hostname 是主机级标识,两进程同 identity 会让 client-go
// 的「租约已被他人持有」判定失效,两副本同时当选)。
Identity string
// LeaseDuration 是租约时长(默认 15s,须大于 RenewDeadline;**必须为
// 整秒且 ≥1s**,#101——client-go 把租约按整秒写入 Lease 资源,亚秒值
// 被截断为 0 秒 ⇒ 竞争者恒判「租约已过期」⇒ 不同 identity 的两个副本
// 同时当选;1500ms 这类非整秒会被截短,对外声明的租约比实际短)。
LeaseDuration time.Duration
// RenewDeadline 是续约窗口(默认 10s;窗口内续约失败即放弃领导权,
// 须满足 > RetryPeriod*1.2,见 New 的校验)。
RenewDeadline time.Duration
// RetryPeriod 是重试间隔(默认 2s;client-go 协议要求显著小于
// RenewDeadline,否则续约窗口内只有一次重试机会)。
RetryPeriod time.Duration
// OnStartedLeading 必填:当选回调,在独立 goroutine 中运行,应阻塞至
// 其入参 ctx 取消(ctx 在失去领导权时被取消);快速返回不会结束选主,
// 只会留下空转的续约循环,单活职责随即失效。
OnStartedLeading func(ctx context.Context)
// OnStoppedLeading 必填:elector 结束回调——client-go 在 LeaderElector
// 退出时无条件触发,不区分退出原因:失去领导权、ctx 取消优雅关停、
// 乃至从未当选就退出(client-go 文档明示 "even if it did not start
// leading")都会调用,因此它不等于「失去领导权」。是否失权请以 Run
// 的返回值为准(ErrLostLeadership);勿在此回调里无条件 log.Fatal——
// 否则非 leader 副本的每次正常关停(滚动发布/缩容)都会以非零码退出。
// client-go 的 LeaderElector 要求该回调非 nil,缺失会导致构造失败。
OnStoppedLeading func()
// OnNewLeader 新leader产生回调(含自己当选;identity 为新 leader 标识)。
OnNewLeader func(identity string)
// ReleaseOnCancel 控制 ctx 取消(优雅关停)时是否立即释放 Lease
// (透传 client-go LeaderElectionConfig.ReleaseOnCancel,默认 false
// 保持既有行为)。
//
// false(默认):关停不释放 Lease,继任者须等租约自然过期才能接管——
// 按 LeaseDuration 缺省 15s 计,每次滚动发布/缩容最长 15s 无人单活。
//
// true:ctx 取消后立即清空 Lease 的 holderIdentity,继任者在 RetryPeriod
// 量级内即可接管(从释放到继任者当选仍有一小段选主空窗,但不再是
// 15s 量级)。
//
// 启用前提(client-go 明示的安全约束):取消 ctx 前必须保证受 Lease
// 保护的单活逻辑已经完成/排空——释放后继任者可立刻当选,若本副本
// 仍有在飞单活逻辑,会出现两个副本同时执行关键路径。
ReleaseOnCancel bool
}
Config 是选主配置。