Kubernetes Lease backend
Latest stable Based on Leader release 0.4.0
Library module
Problem
Section titled “Problem”Preview: Validate API and operational behavior before production adoption.
Preview backend using coordination.k8s.io/v1 Lease objects for single and fixed-slot group election. It offers blocking, future, and coroutine APIs.
When to use it
Section titled “When to use it”Choose it for workloads that already run in Kubernetes and should use native RBAC and namespace boundaries rather than another coordination store.
Coordinates
Section titled “Coordinates”Artifact: io.github.bluetape4k.leader:bluetape4k-leader-k8s
dependencies { implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>")) implementation("io.github.bluetape4k.leader:bluetape4k-leader-k8s")}Core concepts
Section titled “Core concepts”Each acquisition writes a unique fencing token into a Lease holder identity. Update, extend, and release are resource-version/owner conditional; the supplied Fabric8 client is caller-owned.
Quick start
Section titled “Quick start”val elector = KubernetesLeaseLeaderElector( client, KubernetesLeaseOptions(namespace = "operators"))elector.runIfLeader("reconcile") { reconcile() }API by task
Section titled “API by task”Use KubernetesLeaseLeaderElector, suspend, and group variants. Client extension functions provide compact blocking and future calls.
Recommended patterns
Section titled “Recommended patterns”Grant least-privilege get/create/update permissions for Leases in one namespace. Use deterministic names and keep the protected action idempotent.
Integrations
Section titled “Integrations”Spring can create a factory from the client. k8s-lease and k8s-operator examples show scheduled and control-loop use.
Configuration
Section titled “Configuration”Configure namespace, name prefix, wait/lease/minimum lease, retry delay, and group size. Client endpoint, authentication, and lifecycle belong to the application.
Failure modes
Section titled “Failure modes”Contention and resource-version conflicts within the budget skip/retry. RBAC denial, API outage, malformed Lease state, and cleanup failure propagate.
Operations
Section titled “Operations”Monitor Kubernetes API latency, 409 conflicts, 403 errors, lease renewal age, stale objects, and client throttling. Include namespace and Lease name in diagnostics.
Testing
Section titled “Testing”Use a real API server or faithful test environment for two-client conflict, resource-version races, expiry, owner-safe release, group slots, and cancellation.
Workshops and learning path
Section titled “Workshops and learning path”Run k8s-lease first, then k8s-operator. Compare this control-plane dependency with etcd without assuming direct etcd access is equivalent.
Limitations
Section titled “Limitations”Preview API may evolve. Kubernetes API availability, RBAC, and rate limits are on the execution path; Lease ownership does not fence an external database.
Release diagrams
Section titled “Release diagrams”These diagrams are loaded directly from README assets published with the 0.4.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.
leader-k8s architecture diagram
Section titled “leader-k8s architecture diagram”
Release README: leader-k8s/README.md
leader-k8s acquire and release sequence diagram
Section titled “leader-k8s acquire and release sequence diagram”
Release README: leader-k8s/README.md