KubernetesLease
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”checkAlive()
Section titled “checkAlive()”checkAlive():
boolean
Defined in: src/coordination/leases/KubernetesLease.ts:204
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:206
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:185
Release the lease voluntarily. No-op if not held.
Returns
Section titled “Returns”Promise<void>