From f1bbda376134a16a84d9deffb1b5893edd9f4d9a Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Wed, 7 Jan 2015 15:38:11 -0800 Subject: [PATCH] website: Document session behavior and TTL --- .../docs/internals/sessions.html.markdown | 37 +++++++++++++++---- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/website/source/docs/internals/sessions.html.markdown b/website/source/docs/internals/sessions.html.markdown index 7daea5ae87..5b341a64ad 100644 --- a/website/source/docs/internals/sessions.html.markdown +++ b/website/source/docs/internals/sessions.html.markdown @@ -21,8 +21,8 @@ to learn about them without having to go spelunking through the source code. ## Session Design A session in Consul represents a contract that has very specific semantics. -When a session is constructed a node name, a list of health checks, and a -`lock-delay` are provided. The newly constructed session is provided with +When a session is constructed a node name, a list of health checks, behavior, +TTL and a `lock-delay` may be provided. The newly constructed session is provided with a named ID which can be used to refer to it. This ID can be used with the KV store to acquire locks, which are advisory mechanisms for mutual exclusion. Below is a diagram showing the relationship between these components: @@ -38,11 +38,19 @@ situations the session will be *invalidated*: * Any of the health checks are deregistered * Any of the health checks go to the critical state * Session is explicitly destroyed +* TTL expires, if applicable -When a session is invalidated, any of the locks held in association -with the session are released, and the `ModifyIndex` of the key is -incremented. The session is also destroyed during an invalidation -and can no longer be used to acquire further locks. +When a session is invalidated, it is destroyed and can no longer +be used. What happens to the associated locks depends on the +behavior specified at creation time. Consul supports a `release` +and `delete` behavior. The `release` behavior is the default +if not specified. + +If the `release` behavior is being used, any of the locks held in +association with the session are released, and the `ModifyIndex` of the key is incremented. +Alternatively, if the `delete` behavior is used, the key corresponding +to any of the held locks is simply deleted. This can be used to create +ephemeral entries that are automatically deleted by Consul. While this is a simple design, it enables a multitude of usage patterns. By default, the [gossip based failure detector](/docs/internals/gossip.html) @@ -63,6 +71,21 @@ Since Consul APIs allow a session to be force destroyed, this allows systems to be built that require an operator to intervene in the case of a failure, but preclude the possibility of a split-brain. +A third health checking mechanism is session TTLs. When creating +a session a TTL can be specified. If the TTL interval expires without +being renewed, the session has expired and an invalidation is triggered. +This type of failure detector is also known as a heartbeat failure detector. +It is less scalable than the gossip based failure detector as it places +an increased burden on the servers, but may be applicable in some cases. +The contract of a TTL is that it represents a lower bound for invalidation, +meaning Consul will not expire the session before the TTL is reached, but it +is allowed to delay the expiration past the TTL. The TTL is renewed on +session creation, on session renew, and on leader failover. When a TTL +is being used, clients should be aware of clock skew issues, namely that +time may not progress at the same rate on the client as on the Consul servers. +It is best to set conservative TTL values, and to renew in advance of the TTL +to account for network delay and time skew. + The final nuance is that sessions may provide a `lock-delay`. This is a time duration, between 0 and 60 seconds. When a session invalidation takes place, Consul prevents any of the previously held locks from @@ -93,7 +116,7 @@ since the request will fail if given an invalid session. A critical note is that the lock can be released without being the creator of the session. This is by design, as it allows operators to intervene and force terminate a session if necessary. As mentioned above, a session invalidation will also -cause all held locks to be released. When a lock is released, the `LockIndex` +cause all held locks to be released or deleted. When a lock is released, the `LockIndex` does not change, however the `Session` is cleared and the `ModifyIndex` increments. These semantics (heavily borrowed from Chubby), allow the tuple of (Key, LockIndex, Session)