website: Adding guide on leader election

website/source/docs/guides/leader-election.html.markdown

@@ -0,0 +1,73 @@
+---
+layout: "docs"
+page_title: "Leader Election"
+sidebar_current: "docs-guides-leader"
+---
+
+# Leader Election
+
+The goal of this guide is to cover how to build client-side leader election using Consul.
+If you are interested in the leader election used internally to Consul, you want to
+read about the [consensus protocol](/docs/internals/consensus.html) instead.
+
+There are a number of ways that leader election can be built, so our goal is not to
+cover all the possible methods. Instead, we will focus on using Consul's support for
+[sessions](/docs/internals/sessions.html), which allow us to build a system that can
+gracefully handle failures.
+
+## Contending Nodes
+
+The first flow we cover is for nodes who are attempting to acquire leadership
+for a given service. All nodes that are participating should agree on a given
+key being used to coordinate. A good choice is simply:
+
+    service/<service name>/leader
+
+We will refer to this as just `key` for simplicy.
+
+The first step is to create a session. This is done using the /v1/session/create endpoint.
+The session by default makes use of only the gossip failure detector. Additional checks
+can be specified if desired. The session ID returned will be refered to as `session`.
+
+Create `body` to represent the local node. This can be a simple JSON object
+that contains the node's name, port or any application specific information
+that may be needed.
+
+Attempt to `acquire` the `key` by doing a `PUT`. This is something like:
+
+     curl -X PUT -d body http://localhost:8500/v1/kv/key?acquire=session
+
+This will either return `true` or `false`. If `true` is returned, the lock
+has been acquired and the local node is now the leader. If `false` is returned,
+some other node has acquired the lock.
+
+All nodes now remain in an idle waiting state. In this state, we watch for changes
+on `key`. This is because the lock may be released, the node may fail, etc.
+The leader must also watch for changes since it's lock may be released by an operator,
+or automatically released due to a false positive in the failure detector.
+
+Watching for changes is done by doing a blocking query against `key`. If we ever
+notice that the `Session` of the `key` is blank, then there is no leader, and we should
+retry acquiring the lock. Each attempt to acquire the key should be seperated by a timed
+wait. This is because Consul may be enforcing a [`lock-delay`](/docs/internals/sessions.html).
+
+If the leader ever wishes to step down voluntarily, this should be done by simply
+releasing the lock:
+
+     curl -X PUT http://localhost:8500/v1/kv/key?release=session
+
+## Discovering a Leader
+
+The second flow is for nodes who are attempting to discover the leader
+for a given servie. All nodes that are participating should agree on the key
+being used to coordinate, including the contendors. This key will be referred
+to as just `key`.
+
+Clients have a very simple role, they simply read `key` to discover who the current
+leader is. If the key has no associated `Session`, then there is no leader. Otherwise,
+the value of the key will provide all the application-dependent information required.
+
+Clients should also watch the key using a blocking query for any changes. If the leader
+steps down, or fails, then the `Session` associated with the key will be cleared. When
+a new leader is elected, the key value will also be updated.
+

website/source/docs/internals/sessions.html.markdown

@@ -4,11 +4,12 @@ page_title: "Sessions"
 sidebar_current: "docs-internals-sessions"
 ---
 
-# Consensus Protocol
+# Sessions
 
 Consul provides a session mechansim 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 similar to Chubby.
+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).
 
 <div class="alert alert-block alert-warning">
 <strong>Advanced Topic!</strong> This page covers technical details of
@@ -87,7 +88,7 @@ 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,
 since the request will fail if given an invalid session. A critical note is
-that the session ID can be destroyed without being the creator of the session.
+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`,
@@ -105,3 +106,9 @@ that clients must acquire a lock to perform any operation. Any client can
 read, write, and delete a key without owning the corresponding lock. It is not
 the goal of Consul to protect against misbehaving clients.
 
+## Leader Election
+
+The primitives provided by sessions and the locking mechanisms of the KV
+store can be used to build client-side leader election algorithms.
+These are covered in more detail in the [Leader Election guide](/docs/guides/leader-election.html).
+

website/source/layouts/docs.erb

@@ -144,6 +144,10 @@
 					<a href="/docs/guides/external.html">External Services</a>
                     </li>
 
+                    <li<%= sidebar_current("docs-guides-leader") %>>
+					<a href="/docs/guides/leader-election.html">Leader Election</a>
+                    </li>
+
                     <li<%= sidebar_current("docs-guides-datacenters") %>>
 					<a href="/docs/guides/datacenters.html">Multiple Datacenters</a>
                     </li>