leaderelection

package
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 14 Imported by: 0

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

View Source
var ErrLostLeadership = errors.New("k8s leaderelection: lost leadership")

ErrLostLeadership 表示 elector 因失去领导权(续约窗口内续约失败)而退出。 失权意味着本副本已不适合继续单活职责,典型处理是进程退出交由重启, 而非把该错误当成功吞掉。

Functions

func Run

func Run(ctx context.Context, client kubernetes.Interface, cfg Config) error

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 是选主配置。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL