Distributed Lock Service  ·  View 11 of 26  ·  4 · Data

Lock Data Model

Namespace, class, session and hold, with the token defined as a function of the epoch and the commit revision.

Editable source SVG draw.io All views
namespace ns_id PK tenant_id held_lease_quota op_rate_quota cluster_tier lock_class class_id PK ns_id FK key_prefix ttl_min / ttl_max mode X | S enforcement fenced | advisory on_quorum_loss closed | open epoch epoch PK 16-bit etcd_cluster_id advanced_at reason restore | rehome session etcd_lease_id PK spiffe_id ttl_s opened_rev hold lock_key PK etcd_lease_id FK class_id FK grant_rev token = epoch·2^48 + grant_rev holder_meta waiter lock_key + create_rev PK etcd_lease_id FK deadline audit_event cluster_id + revision PK type grant | release | expire | force lock_key spiffe_id token unprotected bool force_release request_id PK revision FK requester / approver reason class_was_fenced 1 : N 1 : N 1 : N 1 : N 1 : N 1 : N 1 : 1 Lock Data Model v 1.0 · owner Platform Architecture · date 2026-09

Decisions

  • The token is not a stored counter. It is the epoch in the top 16 bits and the etcd revision of the granting transaction in the low 48, so it is minted by the commit itself and needs no extra key per lock.
  • A session is an etcd lease owned by one SPIFFE identity at one TTL. Holds attach to it, so renewing one session renews every hold on it in a single keepalive.
  • Force-release has its own record joined to the audit event by revision. The reason and both approvers survive long after the lock key is gone.

Why revision and not a per-key counter

  • A per-key counter must be kept forever or it restarts at one. Four million keys a day would make the counter table the largest thing in the store.
  • etcd revisions are cluster-wide, strictly increasing and never reused, which is stronger than per-key monotonicity. Gaps are expected and harmless.

Headroom

  • 48 bits of revision is 2.8 × 10^14. At a sustained 30,000 commits a second that lasts about 297 years per epoch. Epochs are kept below 2^15 so the token stays positive in a signed 64-bit column, which still allows 32,767 restores or rehomes.
◀  Key Space and Stores, by Authority All views Audit Data Flow  ▶
Solution Architecture v1.0 · Platform Architecture · 2026-09 · 26 views · open source, fully on-premises11-data-model