From 3fc7b208a5723e8a080d37c7861cf018472b5461 Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Tue, 20 May 2014 12:22:16 -0700 Subject: [PATCH] website: Adding guide on leader election --- .../docs/guides/leader-election.html.markdown | 73 +++++++++++++++++++ .../docs/internals/sessions.html.markdown | 13 +++- website/source/layouts/docs.erb | 4 + 3 files changed, 87 insertions(+), 3 deletions(-) create mode 100644 website/source/docs/guides/leader-election.html.markdown diff --git a/website/source/docs/guides/leader-election.html.markdown b/website/source/docs/guides/leader-election.html.markdown new file mode 100644 index 0000000000..6a2a1fc7d5 --- /dev/null +++ b/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//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. + diff --git a/website/source/docs/internals/sessions.html.markdown b/website/source/docs/internals/sessions.html.markdown index f45fffeb35..f573a568c5 100644 --- a/website/source/docs/internals/sessions.html.markdown +++ b/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).
Advanced Topic! 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). + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 1759149eb0..3d6c848083 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -144,6 +144,10 @@ External Services + > + Leader Election + + > Multiple Datacenters