github.com/outbrain/consul@v1.4.5/website/source/docs/internals/sessions.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Sessions"
     4  sidebar_current: "docs-internals-sessions"
     5  description: |-
     6    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.
     7  ---
     8  
     9  # Sessions
    10  
    11  Consul provides a session mechanism which can be used to build distributed locks.
    12  Sessions act as a binding layer between nodes, health checks, and key/value data.
    13  They are designed to provide granular locking and are heavily inspired by
    14  [The Chubby Lock Service for Loosely-Coupled Distributed Systems](http://research.google.com/archive/chubby.html).
    15  
    16  ~> **Advanced Topic!** This page covers technical details of
    17  the internals of Consul. You don't need to know these details to effectively
    18  operate and use Consul. These details are documented here for those who wish
    19  to learn about them without having to go spelunking through the source code.
    20  
    21  ## Session Design
    22  
    23  A session in Consul represents a contract that has very specific semantics.
    24  When a session is constructed, a node name, a list of health checks, a behavior,
    25  a TTL, and a `lock-delay` may be provided. The newly constructed session is provided with
    26  a named ID that can be used to identify it. This ID can be used with the KV
    27  store to acquire locks: advisory mechanisms for mutual exclusion.
    28  
    29  Below is a diagram showing the relationship between these components:
    30  
    31  <div class="center">
    32  ![Consul Sessions](consul-sessions.png)
    33  </div>
    34  
    35  The contract that Consul provides is that under any of the following
    36  situations, the session will be *invalidated*:
    37  
    38  * Node is deregistered
    39  * Any of the health checks are deregistered
    40  * Any of the health checks go to the critical state
    41  * Session is explicitly destroyed
    42  * TTL expires, if applicable
    43  
    44  When a session is invalidated, it is destroyed and can no longer
    45  be used. What happens to the associated locks depends on the
    46  behavior specified at creation time. Consul supports a `release`
    47  and `delete` behavior. The `release` behavior is the default
    48  if none is specified.
    49  
    50  If the `release` behavior is being used, any of the locks held in
    51  association with the session are released, and the `ModifyIndex` of
    52  the key is incremented. Alternatively, if the `delete` behavior is
    53  used, the key corresponding to any of the held locks is simply deleted.
    54  This can be used to create ephemeral entries that are automatically
    55  deleted by Consul.
    56  
    57  While this is a simple design, it enables a multitude of usage
    58  patterns. By default, the
    59  [gossip based failure detector](/docs/internals/gossip.html)
    60  is used as the associated health check. This failure detector allows
    61  Consul to detect when a node that is holding a lock has failed and
    62  to automatically release the lock. This ability provides **liveness** to
    63  Consul locks; that is, under failure the system can continue to make
    64  progress. However, because there is no perfect failure detector, it's possible
    65  to have a false positive (failure detected) which causes the lock to
    66  be released even though the lock owner is still alive. This means
    67  we are sacrificing some **safety**.
    68  
    69  Conversely, it is possible to create a session with no associated
    70  health checks. This removes the possibility of a false positive
    71  and trades liveness for safety. You can be absolutely certain Consul
    72  will not release the lock even if the existing owner has failed.
    73  Since Consul APIs allow a session to be force destroyed, this allows
    74  systems to be built that require an operator to intervene in the
    75  case of a failure while precluding the possibility of a split-brain.
    76  
    77  A third health checking mechanism is session TTLs. When creating
    78  a session, a TTL can be specified. If the TTL interval expires without
    79  being renewed, the session has expired and an invalidation is triggered.
    80  This type of failure detector is also known as a heartbeat failure detector.
    81  It is less scalable than the gossip based failure detector as it places
    82  an increased burden on the servers but may be applicable in some cases.
    83  The contract of a TTL is that it represents a lower bound for invalidation;
    84  that is, Consul will not expire the session before the TTL is reached, but it
    85  is allowed to delay the expiration past the TTL. The TTL is renewed on
    86  session creation, on session renew, and on leader failover. When a TTL
    87  is being used, clients should be aware of clock skew issues: namely,
    88  time may not progress at the same rate on the client as on the Consul servers.
    89  It is best to set conservative TTL values and to renew in advance of the TTL
    90  to account for network delay and time skew.
    91  
    92  The final nuance is that sessions may provide a `lock-delay`. This
    93  is a time duration, between 0 and 60 seconds. When a session invalidation
    94  takes place, Consul prevents any of the previously held locks from
    95  being re-acquired for the `lock-delay` interval; this is a safeguard
    96  inspired by Google's Chubby. The purpose of this delay is to allow
    97  the potentially still live leader to detect the invalidation and stop
    98  processing requests that may lead to inconsistent state. While not a
    99  bulletproof method, it does avoid the need to introduce sleep states
   100  into application logic and can help mitigate many issues. While the
   101  default is to use a 15 second delay, clients are able to disable this
   102  mechanism by providing a zero delay value.
   103  
   104  ## K/V Integration
   105  
   106  Integration between the KV store and sessions is the primary
   107  place where sessions are used. A session must be created prior to use
   108  and is then referred to by its ID.
   109  
   110  The KV API is extended to support an `acquire` and `release` operation.
   111  The `acquire` operation acts like a Check-And-Set operation except it
   112  can only succeed if there is no existing lock holder (the current lock holder
   113  can re-`acquire`, see below). On success, there is a normal key update, but
   114  there is also an increment to the `LockIndex`, and the `Session` value is
   115  updated to reflect the session holding the lock.
   116  
   117  If the lock is already held by the given session during an `acquire`, then
   118  the `LockIndex` is not incremented but the key contents are updated. This
   119  lets the current lock holder update the key contents without having to give
   120  up the lock and reacquire it.
   121  
   122  Once held, the lock can be released using a corresponding `release` operation,
   123  providing the same session. Again, this acts like a Check-And-Set operation
   124  since the request will fail if given an invalid session. A critical note is
   125  that the lock can be released without being the creator of the session.
   126  This is by design as it allows operators to intervene and force-terminate
   127  a session if necessary. As mentioned above, a session invalidation will also
   128  cause all held locks to be released or deleted. When a lock is released, the `LockIndex`
   129  does not change; however, the `Session` is cleared and the `ModifyIndex` increments.
   130  
   131  These semantics (heavily borrowed from Chubby), allow the tuple of (Key, LockIndex, Session)
   132  to act as a unique "sequencer". This `sequencer` can be passed around and used
   133  to verify if the request belongs to the current lock holder. Because the `LockIndex`
   134  is incremented on each `acquire`, even if the same session re-acquires a lock,
   135  the `sequencer` will be able to detect a stale request. Similarly, if a session is
   136  invalided, the Session corresponding to the given `LockIndex` will be blank.
   137  
   138  To be clear, this locking system is purely *advisory*. There is no enforcement
   139  that clients must acquire a lock to perform any operation. Any client can
   140  read, write, and delete a key without owning the corresponding lock. It is not
   141  the goal of Consul to protect against misbehaving clients.
   142  
   143  ## Leader Election
   144  
   145  The primitives provided by sessions and the locking mechanisms of the KV
   146  store can be used to build client-side leader election algorithms.
   147  These are covered in more detail in the [Leader Election guide](/docs/guides/leader-election.html).
   148  
   149  ## Prepared Query Integration
   150  
   151  Prepared queries may be attached to a session in order to automatically delete
   152  the prepared query when the session is invalidated.