open-consul/website/source/docs/guides/leader-election.html.md

---
layout: "docs"
page_title: "Leader Election"
sidebar_current: "docs-guides-leader"
description: |-
  This guide describes how to build client-side leader election using Consul. If you are interested in the leader election used internally to Consul, please refer to the consensus protocol documentation instead.
---

# Leader Election

This guide describes how to build client-side leader election using Consul. If you
are interested in the leader election used internally by Consul, please refer to the
[consensus protocol](/docs/internals/consensus.html) documentation 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). Sessions allow us to build a system that
can gracefully handle failures.

-> **Note:** JSON output in this guide has been pretty-printed for easier reading. Actual values returned from the API will not be formatted.

## Contending Nodes

Let's imagine we have a set of nodes who are attempting to acquire leadership
for a given service. All nodes that are participating should agree on a given
key to coordinate. A good pattern is simply:

```text
service/<service name>/leader
```

We'll abbreviate this pattern as simply `<key>` for the rest of this guide.

The first step is to create a session using the
[Session HTTP API](/api/session.html#session_create):

```text
curl  -X PUT -d '{"Name": "dbservice"}' \
  http://localhost:8500/v1/session/create
 ```

This will return a JSON object containing the session ID:

```text
{
  "ID": "4ca8e74b-6350-7587-addf-a18084928f3c"
}
```

The next step is to acquire a session for a given key from this node
using the PUT method on a [KV entry](/api/kv.html) with the
`?acquire=<session>` query parameter. The `<body>` of the PUT should be a
JSON object representing the local node. This value is opaque to
Consul, but it should contain whatever information clients require to
communicate with your application (e.g., it could be a JSON object
that contains the node's name and the application's port).

Attempt to `acquire` the `<key>`. This will look something like (note that
`<session>` is the ID returned by the call to
[`/v1/session/create`](/api/session.html#session_create)):

```text
curl -X PUT -d <body> http://localhost:8500/v1/kv/<key>?acquire=<session>
 ```

This will either return `true` or `false`. If `true`, 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 its lock may be released by an operator
or automatically released due to a false positive in the failure detector.

By default, the session makes use of only the gossip failure detector. That
is, the session is considered held by a node as long as the default Serf health check
has not declared the node unhealthy. Additional checks can be specified if desired.

Watching for changes is done via a blocking query against `<key>`. If we ever
notice that the `Session` of the `<key>` is blank, there is no leader, and we should
retry lock acquisition. Each attempt to acquire the key should be separated 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:

```text
curl -X PUT http://localhost:8500/v1/kv/<key>?release=<session>
```

## Discovering a Leader

Another common practice regarding leader election is for nodes to wish to identify the
leader for a given service.

As with leader election, all nodes that are participating should agree on the key
being used to coordinate. 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:

```text
curl  http://localhost:8500/v1/kv/<key>
[
  {
    "Session": "4ca8e74b-6350-7587-addf-a18084928f3c",
    "Value": "Ym9keQ==",
    "Flags": 0,
    "Key": "<key>",
    "LockIndex": 1,
    "ModifyIndex": 29,
    "CreateIndex": 29
  }
]
```

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 as a Base64 encoded blob in
the `Value` field.

You can query the
[`/v1/session/info`](/api/session.html#session_info)
endpoint to get details about the session:

```text
curl http://localhost:8500/v1/session/info/4ca8e74b-6350-7587-addf-a18084928f3c
[
  {
    "LockDelay": 1.5e+10,
    "Checks": [
      "serfHealth"
    ],
    "Node": "consul-primary-bjsiobmvdij6-node-lhe5ihreel7y",
    "Name": "dbservice",
    "ID": "4ca8e74b-6350-7587-addf-a18084928f3c",
    "CreateIndex": 28
  }
]
```

Clients should also watch the key using a blocking query for any
changes. If the leader steps down or fails, the `Session` associated
with the key will be cleared. When a new leader is elected, the key
value will also be updated.

Using the `acquire` param is optional. This means
that if you use leader election to update a key, you must not update the key
without the acquire parameter.
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00			`---`
			`layout: "docs"`
			`page_title: "Leader Election"`
			`sidebar_current: "docs-guides-leader"`
Use new Markdown syntaxes and add SEO descriptions 2014-10-19 23:40:10 +00:00			`description: \|-`
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`This guide describes how to build client-side leader election using Consul. If you are interested in the leader election used internally to Consul, please refer to the consensus protocol documentation instead.`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00			`---`

			`# Leader Election`

Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`This guide describes how to build client-side leader election using Consul. If you`
			`are interested in the leader election used internally by Consul, please refer to the`
			`[consensus protocol](/docs/internals/consensus.html) documentation instead.`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
			`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`
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`[sessions](/docs/internals/sessions.html). Sessions allow us to build a system that`
			`can gracefully handle failures.`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written. 2016-11-25 16:00:02 +00:00			`-> Note: JSON output in this guide has been pretty-printed for easier reading. Actual values returned from the API will not be formatted.`
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00			`## Contending Nodes`

Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`Let's imagine we have a set of nodes who are attempting to acquire leadership`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00			`for a given service. All nodes that are participating should agree on a given`
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`key to coordinate. A good pattern is simply:`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
Use new Markdown syntaxes and add SEO descriptions 2014-10-19 23:40:10 +00:00			```text
			`service/<service name>/leader`
			```
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			We'll abbreviate this pattern as simply `<key>` for the rest of this guide.
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`The first step is to create a session using the`
Update API docs 2017-04-04 16:33:22 +00:00			`[Session HTTP API](/api/session.html#session_create):`
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00
			```text
			`curl -X PUT -d '{"Name": "dbservice"}' \`
			`http://localhost:8500/v1/session/create`
			```

Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`This will return a JSON object containing the session ID:`
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00
			```text
			`{`
			`"ID": "4ca8e74b-6350-7587-addf-a18084928f3c"`
			`}`
			```
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`The next step is to acquire a session for a given key from this node`
Update API docs 2017-04-04 16:33:22 +00:00			`using the PUT method on a [KV entry](/api/kv.html) with the`
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written. 2016-11-25 16:00:02 +00:00			`?acquire=<session>` query parameter. The `<body>` of the PUT should be a
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`JSON object representing the local node. This value is opaque to`
			`Consul, but it should contain whatever information clients require to`
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00			`communicate with your application (e.g., it could be a JSON object`
			`that contains the node's name and the application's port).`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			Attempt to `acquire` the `<key>`. This will look something like (note that
			`<session>` is the ID returned by the call to
Update API docs 2017-04-04 16:33:22 +00:00			[`/v1/session/create`](/api/session.html#session_create)):
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
Use new Markdown syntaxes and add SEO descriptions 2014-10-19 23:40:10 +00:00			```text
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00			`curl -X PUT -d <body> http://localhost:8500/v1/kv/<key>?acquire=<session>`
Use new Markdown syntaxes and add SEO descriptions 2014-10-19 23:40:10 +00:00			```
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			This will either return `true` or `false`. If `true`, the lock has been acquired and
			the local node is now the leader. If `false` is returned, some other node has acquired
			`the lock.`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
			`All nodes now remain in an idle waiting state. In this state, we watch for changes`
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00			on `<key>`. This is because the lock may be released, the node may fail, etc.
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`The leader must also watch for changes since its lock may be released by an operator`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00			`or automatically released due to a false positive in the failure detector.`

Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written. 2016-11-25 16:00:02 +00:00			`By default, the session makes use of only the gossip failure detector. That`
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`is, the session is considered held by a node as long as the default Serf health check`
			`has not declared the node unhealthy. Additional checks can be specified if desired.`

			Watching for changes is done via a blocking query against `<key>`. If we ever
			notice that the `Session` of the `<key>` is blank, there is no leader, and we should
			`retry lock acquisition. Each attempt to acquire the key should be separated by a timed`
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00			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:`

Use new Markdown syntaxes and add SEO descriptions 2014-10-19 23:40:10 +00:00			```text
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00			`curl -X PUT http://localhost:8500/v1/kv/<key>?release=<session>`
Use new Markdown syntaxes and add SEO descriptions 2014-10-19 23:40:10 +00:00			```
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
			`## Discovering a Leader`

Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			`Another common practice regarding leader election is for nodes to wish to identify the`
			`leader for a given service.`

Update leader-election.html.markdown Remove duplicate 'leader' 2016-02-14 14:32:23 +00:00			`As with leader election, all nodes that are participating should agree on the key`
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00			being used to coordinate. This key will be referred to as just `key`.
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00			Clients have a very simple role, they simply read `<key>` to discover who the current
			`leader is:`

			```text
			`curl http://localhost:8500/v1/kv/<key>`
			`[`
			`{`
			`"Session": "4ca8e74b-6350-7587-addf-a18084928f3c",`
			`"Value": "Ym9keQ==",`
			`"Flags": 0,`
			`"Key": "<key>",`
			`"LockIndex": 1,`
			`"ModifyIndex": 29,`
			`"CreateIndex": 29`
			`}`
			`]`
			```

Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written. 2016-11-25 16:00:02 +00:00			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 as a Base64 encoded blob in`
			the `Value` field.
Website: GH-730 and cleanup for docs/guides/leader-election.html. 2015-02-28 05:08:41 +00:00
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written. 2016-11-25 16:00:02 +00:00			`You can query the`
Update API docs 2017-04-04 16:33:22 +00:00			[`/v1/session/info`](/api/session.html#session_info)
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written. 2016-11-25 16:00:02 +00:00			`endpoint to get details about the session:`
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00
			```text
			`curl http://localhost:8500/v1/session/info/4ca8e74b-6350-7587-addf-a18084928f3c`
			`[`
			`{`
			`"LockDelay": 1.5e+10,`
			`"Checks": [`
			`"serfHealth"`
			`],`
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written. 2016-11-25 16:00:02 +00:00			`"Node": "consul-primary-bjsiobmvdij6-node-lhe5ihreel7y",`
updates to leader election documentation Clarify the steps involved in the leader election process. - provide examples of creating a session - provide links to appropriate documentation 2014-12-05 19:09:45 +00:00			`"Name": "dbservice",`
			`"ID": "4ca8e74b-6350-7587-addf-a18084928f3c",`
			`"CreateIndex": 28`
			`}`
			`]`
			```
website: Adding guide on leader election 2014-05-20 19:22:16 +00:00
Documentation pass I was reviewing some docs and found a few issues. 1. Fixed some spelling mistakes. 2. Re-formatted some paragraphs. 3. Changed some potentially loaded language. 4. Fixed some grammar issues. 5. Tried to consistently use syntax-highlighting. 6. Fixed post-period spacing. 7. Fixed some formatting issues and inconsistency. 8. All "notes" are either proper notes or re-written. 2016-11-25 16:00:02 +00:00			`Clients should also watch the key using a blocking query for any`
			changes. If the leader steps down or fails, the `Session` associated
			`with the key will be cleared. When a new leader is elected, the key`
			`value will also be updated.`
Clarification around locking (#3853) 2018-02-01 20:08:06 +00:00
			Using the `acquire` param is optional. This means
			`that if you use leader election to update a key, you must not update the key`
			`without the acquire parameter.`