etcd backend

Library module

Problem

Preview: Validate API and operational behavior before production adoption.

Preview backend using etcd v3 leases and the jetcd Lock service for single and group election, with blocking, future, coroutine, and virtual-thread surfaces.

When to use it

Use it when etcd is already a reliable control-plane dependency and lease semantics fit the workload.

Coordinates

Artifact: io.github.bluetape4k.leader:bluetape4k-leader-etcd

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.leader:bluetape4k-leader-etcd")
}

Core concepts

Acquisition creates a lease and lock key; owner-safe release and extension use the returned token. The supplied jetcd client is caller-owned.

Quick start

val elector = EtcdLeaderElector(
    client,
    EtcdLeaderElectionOptions(keyPrefix = "/apps/orders/leader")
)
elector.runIfLeader("reconcile") { reconcile() }

API by task

Use EtcdLeaderElector, suspend, virtual-thread, or group variants. Factories supply Core and framework integrations.

Recommended patterns

Use a dedicated prefix and least-privilege credentials. Keep actions idempotent and account for lease loss during pauses or partitions.

Integrations

Spring can construct factories from a client. The etcd-reconciler example demonstrates a control-loop workload.

Configuration

Configure endpoint in the caller-owned client, key prefix, wait/lease/minimum lease, retry delay, and cleanup timeout budget.

Failure modes

Contention skips. Lease grant, keepalive, lock, cleanup timeout, authentication, and transport failures propagate after classification.

Operations

Watch lease keepalive, request latency, compaction/cluster health, cleanup failures, and skipped work. Client closure belongs to the application.

Testing

Use a real etcd container for acquire/release, lease expiry, key encoding, cleanup timeout, group slots, and cancellation.

Workshops and learning path

Run etcd-reconciler, then compare etcd leases with Consul sessions and Kubernetes Lease objects.

Limitations

Preview API may evolve. etcd availability is now on the job path; a lease is not a business-side fencing token.

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-etcd architecture diagram

Release README: leader-etcd/README.md

Sources

Elector · Options · Stable guide