KubernetesLease
Ce contenu n’est pas encore disponible dans votre langue.
Defined in: src/coordination/leases/KubernetesLease.ts:67
Lease backed by a Kubernetes coordination.k8s.io/v1/Lease object.
Self-contained — speaks the K8s REST API directly, no client-library
dependency. Designed for use behind ClusterSingleton so split-brain
is impossible: at most one Pod can hold the lease at a time, K8s
arbitrates via optimistic concurrency control.
Lifecycle:
-
acquire() — GET the lease object. If it doesn’t exist, CREATE it with
holderIdentity = settings.owner. If it does exist and either it’s already ours or the previous holder’srenewTime + ttlhas passed, PUT a new spec with our owner + a freshacquireTime/renewTime. Returns true on success, false on a live conflict. Optimistic-write 409 conflicts are retried up toacquireRetriestimes. -
renewal loop — every
renewalIntervalMs(defaultttl/3), GET + PUT to bumprenewTime. A 409 / 404 / network error here is treated as ‘lease lost’ and firesonLost(reason). -
release() — DELETE the lease (404 is treated as success). Cancels the renewal timer.
Failure modes that fire onLost:
- PUT during renewal returns 409 (someone else won a race after we read the resourceVersion).
- PUT during renewal returns 404 (someone deleted the lease).
- Network error during renewal that the renewal-loop’s retry budget can’t absorb.
- The K8s API server is unreachable for longer than
ttlMs.
Implements
Section titled “Implements”Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new KubernetesLease(
settings):KubernetesLease
Defined in: src/coordination/leases/KubernetesLease.ts:75
Parameters
Section titled “Parameters”settings
Section titled “settings”Returns
Section titled “Returns”KubernetesLease
Methods
Section titled “Methods”acquire()
Section titled “acquire()”acquire():
Promise<boolean>
Defined in: src/coordination/leases/KubernetesLease.ts:108
Try to acquire the lease. Resolves true on success, false on contention.
Returns
Section titled “Returns”Promise<boolean>
Implementation of
Section titled “Implementation of”acquireWithToken()
Section titled “acquireWithToken()”acquireWithToken():
Promise<{token:string; } |null>
Defined in: src/coordination/leases/KubernetesLease.ts:124
Fencing-token variant: returns a backend-issued token assembled
from the K8s Lease object’s metadata.resourceVersion and the
spec.leaseTransitions counter — both monotonically bumped by
the API server on every successful PUT. The combination is
unique per acquire across the lease’s lifetime, so a
late-arriving “I acquired” can be distinguished from a fresh
one by its token.
Format: <resourceVersion>/<leaseTransitions> (resourceVersion
is opaque K8s state; leaseTransitions is decimal).
Returns
Section titled “Returns”Promise<{ token: string; } | null>
Implementation of
Section titled “Implementation of”checkAlive()
Section titled “checkAlive()”checkAlive():
boolean
Defined in: src/coordination/leases/KubernetesLease.ts:225
True if this process currently owns the lease. Purely local — no IO.
Returns
Section titled “Returns”boolean
Implementation of
Section titled “Implementation of”onLost()
Section titled “onLost()”onLost(
handler): () =>void
Defined in: src/coordination/leases/KubernetesLease.ts:227
Register a handler fired when ownership is lost unexpectedly.
Parameters
Section titled “Parameters”handler
Section titled “handler”(reason) => void
Returns
Section titled “Returns”() => void
Implementation of
Section titled “Implementation of”release()
Section titled “release()”release():
Promise<void>
Defined in: src/coordination/leases/KubernetesLease.ts:206
Release the lease voluntarily. No-op if not held.
Returns
Section titled “Returns”Promise<void>