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

Key Space and Stores, by Authority

One store answers who holds what. Everything else is derived, declared or evidence.

Editable source SVG draw.io All views
Authoritative · lock log (etcd, linearizable) /sys Epoch record epoch + cluster ID Shard map versioned /l · held Exclusive holder on session lease Shared holders one key each /q · fair classes Waiter keys create revision Rebuildable · advisory Wait queue arbiter memory Watch stream from revision Evidence · asynchronous Audit store ClickHouse · 90 d Audit archive MinIO · 1 y / 7 y Declared · Git Lock classes TTL · mode · fenced Prefix grants identity → prefix revisions nightly Key Space and Stores, by Authority Data store Queue / topic Security / platform event / async batch Only the top box answers who holds what. Everything else can be lost and rebuilt without a double grant. v 1.0 · owner Platform Architecture · date 2026-09

Decisions

  • The etcd key space is split into /sys for the epoch record and shard map, /l for held locks and /q for waiter keys on fair classes. RBAC is by prefix: the tailer reads everything and writes nothing.
  • An exclusive holder is one key attached to the session's etcd lease. When the lease goes, the key goes in the same committed revocation, so a crashed holder cannot leave a key behind.
  • Shared holders are one key each under the lock's prefix. An exclusive grant compares the whole range empty in the same transaction, so no shared holder can slip in between.

What can be lost without harm

  • The arbiter's wait queue: waiters retry and order is re-established. Declared best-effort.
  • The watch stream: a waiter polls. A missed event delays a grant and cannot produce one.
  • The audit store: rebuilt from archive plus a tailer replay. Investigation degrades; safety does not.

Assumptions

  • Live lock state stays under 2 GB. At 512 bytes a record, 250,000 held leases are about 128 MB, which leaves room for revision history between compactions.
◀  How a Key Finds Its Class and Its Cluster All views Lock Data Model  ▶
Solution Architecture v1.0 · Platform Architecture · 2026-09 · 26 views · open source, fully on-premises10-key-space-and-stores