diff --git a/website/source/api/kv.html.md b/website/source/api/kv.html.md index 339e6e7d73..572a2a80c8 100644 --- a/website/source/api/kv.html.md +++ b/website/source/api/kv.html.md @@ -182,8 +182,8 @@ The table below shows this endpoint's support for index is non-zero, the key is only set if the index matches the `ModifyIndex` of that key. -- `acquire` `(string: "")` - Specifies to use a lock acquisition operation. This - is useful as it allows leader election to be built on top of Consul. If the +- `acquire` `(string: "")` - Supply a session ID to use in a lock acquisition operation. + This is useful as it allows leader election to be built on top of Consul. If the lock is not held and the session is valid, this increments the `LockIndex` and sets the `Session` value of the key in addition to updating the key contents. A key does not need to exist to be acquired. If the lock is already held by @@ -196,7 +196,7 @@ The table below shows this endpoint's support for For an example of how to use the lock feature, see the [Leader Election Guide] (/docs/guides/leader-election.html). -- `release` `(string: "")` - Specifies to use a lock release operation. This is +- `release` `(string: "")` - Supply a session ID to use in a release operation. This is useful when paired with `?acquire=` as it allows clients to yield a lock. This will leave the `LockIndex` unmodified but will clear the associated `Session` of the key. The key must be held by this session to be unlocked. diff --git a/website/source/api/session.html.md b/website/source/api/session.html.md index ff59a779e8..dde6027bf2 100644 --- a/website/source/api/session.html.md +++ b/website/source/api/session.html.md @@ -35,7 +35,8 @@ The table below shows this endpoint's support for the datacenter of the agent being queried. This is specified as part of the URL as a query parameter. Using this across datacenters is not recommended. -- `LockDelay` `(string: "15s")` - Specifies the duration for the lock delay. +- `LockDelay` `(string: "15s")` - Specifies the duration for the lock delay. This + must be greater than `0`. - `Node` `(string: "")` - Specifies the name of the node. This must refer to a node that is already registered. @@ -55,8 +56,9 @@ The table below shows this endpoint's support for - `TTL` `(string: "")` - Specifies the number of seconds (between 10s and 86400s). If provided, the session is invalidated if it is not renewed before the TTL expires. The lowest practical TTL should be used to keep the number of - managed sessions low. When locks are forcibly expired, such as during a leader - election, sessions may not be reaped for up to double this TTL, so long TTL + managed sessions low. When locks are forcibly expired, such as when following + the [leader election pattern](/docs/guides/leader-election.html) in an application, + sessions may not be reaped for up to double this TTL, so long TTL values (> 1 hour) should be avoided. ### Sample Payload