Status: src/coordination/leases/KubernetesLease.ts is a stub with the protocol fully described in its JSDoc but no network code yet.
Recommended approach: own REST calls (no peer-dep). The K8s Lease API is small enough (3 endpoints) that wrapping @kubernetes/client-node would cost more in dependency weight (~3 MB) than it saves in code. We do our own fetch + auth + TLS, reading the bearer token + CA cert from the standard ServiceAccount mount points.
Protocol (per JSDoc):
GET /apis/coordination.k8s.io/v1/namespaces/<ns>/leases/<name> — read current state including resourceVersion.- Optimistic
PUT with resourceVersion set — server returns 409 Conflict on race, we re-read + retry.
- Renewal loop bumps
spec.renewTime every ttl/3 seconds.
- Release:
PATCH to clear spec.holderIdentity (or just let TTL expire on graceful shutdown).
Components:
| File |
Task |
| src/coordination/leases/KubernetesLease.ts |
replace stub with real impl |
| src/coordination/leases/k8sApi.ts (new) |
low-level fetch + auth + TLS |
| tests/unit/coordination/KubernetesLease.test.ts (new) |
mock-fetch tests + optional live test against kind/k3d (env-gated) |
| examples/coordination/k8s-lease-singleton.ts (new) |
E2E example with ClusterSingleton + K8s lease |
Estimate: 2-4 days. Recommended first — smallest cone, clearest win.
Verification:
- Unit tests against a fetch mock.
- Live integration test gated on
K8S_ENDPOINT etc. (skipped when missing — same pattern as the MinIO tests).
- Manual: example runs against a kind/k3d cluster and a ClusterSingleton survives a forced pod restart.
See the roadmap plan for full context (item 1 of 5).
Status: src/coordination/leases/KubernetesLease.ts is a stub with the protocol fully described in its JSDoc but no network code yet.
Recommended approach: own REST calls (no peer-dep). The K8s Lease API is small enough (3 endpoints) that wrapping @kubernetes/client-node would cost more in dependency weight (~3 MB) than it saves in code. We do our own fetch + auth + TLS, reading the bearer token + CA cert from the standard ServiceAccount mount points.
Protocol (per JSDoc):
GET /apis/coordination.k8s.io/v1/namespaces/<ns>/leases/<name>— read current state includingresourceVersion.PUTwithresourceVersionset — server returns 409 Conflict on race, we re-read + retry.spec.renewTimeeveryttl/3seconds.PATCHto clearspec.holderIdentity(or just let TTL expire on graceful shutdown).Components:
Estimate: 2-4 days. Recommended first — smallest cone, clearest win.
Verification:
K8S_ENDPOINTetc. (skipped when missing — same pattern as the MinIO tests).See the roadmap plan for full context (item 1 of 5).