status-im/consul
2
0
Fork 0
mirror of https://github.com/status-im/consul.git synced 2025-01-22 11:40:06 +00:00
Code Issues Projects Releases Wiki Activity

Website: cleanup for docs/internals/sessions.html.

Browse Source
This commit is contained in:
Ryan Breen 2015-04-15 14:47:15 -04:00
parent 507917748a
commit 0696a45b43
1 changed files with 35 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
website/source/docs/internals/sessions.html.markdown
View File

@ -3,15 +3,15 @@ layout: "docs"
page_title: "Sessions"
sidebar_current: "docs-internals-sessions"
description: |-
Consul provides a session mechanism which can be used to build distributed locks. Sessions act as a binding layer between nodes, health checks, and key/value data. They are designed to provide granular locking, and are heavily inspired by The Chubby Lock Service for Loosely-Coupled Distributed Systems.
Consul provides a session mechanism which can be used to build distributed locks. Sessions act as a binding layer between nodes, health checks, and key/value data. They are designed to provide granular locking and are heavily inspired by The Chubby Lock Service for Loosely-Coupled Distributed Systems.
---
# Sessions
Consul provides a session mechanism which can be used to build distributed locks.
Sessions act as a binding layer between nodes, health checks, and key/value data.
They are designed to provide granular locking, and are heavily inspired
by [The Chubby Lock Service for Loosely-Coupled Distributed Systems](http://research.google.com/archive/chubby.html).
They are designed to provide granular locking and are heavily inspired by
[The Chubby Lock Service for Loosely-Coupled Distributed Systems](http://research.google.com/archive/chubby.html).
~> **Advanced Topic!** This page covers technical details of
the internals of Consul. You don't need to know these details to effectively
@ -21,10 +21,11 @@ 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, 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.
When a session is constructed, a node name, a list of health checks, a behavior,
a TTL, and a `lock-delay` may be provided. The newly constructed session is provided with
a named ID that can be used to identify it. This ID can be used with the KV
store to acquire locks: advisory mechanisms for mutual exclusion.
Below is a diagram showing the relationship between these components:
<div class="center">
@ -32,7 +33,7 @@ Below is a diagram showing the relationship between these components:
</div>
The contract that Consul provides is that under any of the following
situations the session will be *invalidated*:
situations, the session will be *invalidated*:
* Node is deregistered
* Any of the health checks are deregistered
@ -44,46 +45,48 @@ 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 none is 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.
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)
patterns. By default, the
[gossip based failure detector](/docs/internals/gossip.html)
is used as the associated health check. This failure detector allows
Consul to detect when a node that is holding a lock has failed, and
Consul to detect when a node that is holding a lock has failed and
to automatically release the lock. This ability provides **liveness** to
Consul locks, meaning under failure the system can continue to make
Consul locks; that is, under failure the system can continue to make
progress. However, because there is no perfect failure detector, it's possible
to have a false positive (failure detected) which causes the lock to
be released even though the lock owner is still alive. This means
we are sacrificing some **safety**.
Conversely, it is possible to create a session with no associated
health checks. This removes the possibility of a false positive,
health checks. This removes the possibility of a false positive
and trades liveness for safety. You can be absolutely certain Consul
will not release the lock even if the existing owner has failed.
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.
case of a failure while precluding 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
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
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;
that is, 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
is being used, clients should be aware of clock skew issues: namely,
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
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
@ -94,30 +97,30 @@ inspired by Google's Chubby. The purpose of this delay is to allow
the potentially still live leader to detect the invalidation and stop
processing requests that may lead to inconsistent state. While not a
bulletproof method, it does avoid the need to introduce sleep states
into application logic, and can help mitigate many issues. While the
into application logic and can help mitigate many issues. While the
default is to use a 15 second delay, clients are able to disable this
mechanism by providing a zero delay value.
## KV Integration
## K/V Integration
Integration between the Key/Value store and sessions are the primary
place where sessions are used. A session must be created prior to use,
Integration between the Key/Value store and sessions is the primary
place where sessions are used. A session must be created prior to use
and is then referred to by its ID.
The Key/Value API is extended to support an `acquire` and `release` operation.
The `acquire` operation acts like a Check-And-Set operation, except it
The `acquire` operation acts like a Check-And-Set operation except it
can only succeed if there is no existing lock holder. On success, there
is a normal key update, but there is also an increment to the `LockIndex`,
and the `Session` value is updated to reflect the session holding the lock.
Once held, the lock can be released using a corresponding `release` operation,
providing the same session. Again, this acts like a Check-And-Set operations,
providing the same session. Again, this acts like a Check-And-Set operations
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
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 or deleted. When a lock is released, the `LockIndex`
does not change, however the `Session` is cleared and the `ModifyIndex` increments.
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)
to act as a unique "sequencer". This `sequencer` can be passed around and used