Key/Value Store
Model
The KV store is a hierarchical map of string keys to byte values, held in Raft on servers. Keys are flat strings that merely look like paths (config/app/db.json); there are no real directories, but prefix queries (?recurse) let you read a subtree. Values are limited to 512 KB, and every write carries a ModifyIndex you can use for optimistic concurrency.
Consistency and concurrency
Reads default to a leader-forwarded but potentially slightly stale mode; ?consistent forces a Raft round-trip and ?stale allows any server to answer, trading freshness for latency and read scale. Check-and-set is done with ?cas=<index>: cas=0 means create only if absent, which makes it a safe lock primitive. For anything more complex than a single key, use sessions: create a session (optionally with a TTL and behavior release or delete), then PUT key?acquire=<session>. If the session expires (missed renewals), the key is released or deleted automatically - the basis of leader election and the consul lock command.
Traps
- KV data is not stored on client agents and is not present on disk of clients.
- A lock acquired without a session renewal loop will silently break when the TTL expires.
acquirefails if another session holds the key; the response tells you the current holder.- KV values are not encrypted at rest by gossip encryption; gossip encryption protects gossip, TLS protects RPC.
Worked example
To implement a distributed mutex: create a session with ttl=15s, start a renewal goroutine, then attempt PUT /v1/kv/locks/db?acquire=<session>. Only one writer gets true; on crash the session expires and the key frees.