2014-02-08 00:41:03 +00:00
---
layout: "docs"
2014-02-19 01:37:23 +00:00
page_title: "Upgrading Consul"
2014-02-08 00:41:03 +00:00
sidebar_current: "docs-upgrading-upgrading"
2014-10-19 23:40:10 +00:00
description: |-
Consul is meant to be a long-running agent on any nodes participating in a Consul cluster. These nodes consistently communicate with each other. As such, protocol level compatibility and ease of upgrades is an important thing to keep in mind when using Consul.
2014-02-08 00:41:03 +00:00
---
2014-02-19 01:37:23 +00:00
# Upgrading Consul
2014-02-08 00:41:03 +00:00
2014-02-19 01:37:23 +00:00
Consul is meant to be a long-running agent on any nodes participating in a
Consul cluster. These nodes consistently communicate with each other. As such,
2014-02-08 00:41:03 +00:00
protocol level compatibility and ease of upgrades is an important thing to
2014-02-19 01:37:23 +00:00
keep in mind when using Consul.
2014-02-08 00:41:03 +00:00
2014-02-19 01:37:23 +00:00
This page documents how to upgrade Consul when a new version is released.
2014-02-08 00:41:03 +00:00
2014-06-11 18:25:55 +00:00
## Standard Upgrades
2014-02-08 00:41:03 +00:00
2014-06-11 18:25:55 +00:00
For upgrades we strive to ensure backwards compatibility. To support this,
nodes gossip their protocol version and builds. This enables clients and
servers to intelligently enable new features when available, or to gracefully
fallback to a backward compatible mode of operation otherwise.
For most upgrades, the process is simple. Assuming the current version of
Consul is A, and version B is released.
1. On each server, install version B of Consul.
2. Shut down version A, restart with version B.
3. Once all the servers are upgraded, begin a rollout of clients following
the same process.
4. Done! You are now running the latest Consul agent. You can verify this
by running `consul members` to make sure all members have the latest
build and highest protocol version.
## Backward Incompatible Upgrades
In some cases, a backwards incompatible update may be released. This has not
been an issue yet, but to support upgrades we support setting an explicit
protocol version. This disables incompatible features and enables a 2-phase upgrade.
For the steps below, assume you're running version A of Consul, and then
version B comes out.
2014-02-08 00:41:03 +00:00
2014-02-19 01:37:23 +00:00
1. On each node, install version B of Consul.
2014-02-08 00:41:03 +00:00
2. Shut down version A, and start version B with the `-protocol=PREVIOUS`
flag, where "PREVIOUS" is the protocol version of version A (which can
2014-03-09 22:57:03 +00:00
be discovered by running `consul -v` or `consul members` ).
2014-02-08 00:41:03 +00:00
3. Once all nodes are running version B, go through every node and restart
the version B agent _without_ the `-protocol` flag.
2014-02-19 01:37:23 +00:00
4. Done! You're now running the latest Consul agent speaking the latest protocol.
2014-03-09 22:57:03 +00:00
You can verify this is the case by running `consul members` to
2014-02-08 00:41:03 +00:00
make sure all members are speaking the same, latest protocol version.
The key to making this work is the [protocol compatibility ](/docs/compatibility.html )
2014-02-19 01:37:23 +00:00
of Consul. The protocol version system is discussed below.
2014-02-08 00:41:03 +00:00
## Protocol Versions
2014-02-19 01:37:23 +00:00
By default, Consul agents speak the latest protocol they can. However, each
new version of Consul is also able to speak the previous protocol, if there
2014-02-08 00:41:03 +00:00
were any protocol changes.
2014-02-19 01:37:23 +00:00
You can see what protocol versions your version of Consul understands by
running `consul -v` . You'll see output similar to that below:
2014-02-08 00:41:03 +00:00
```
2014-02-19 01:37:23 +00:00
$ consul -v
2016-08-26 00:12:02 +00:00
Consul v0.7.0
Protocol 2 spoken by default, understands 2 to 3 (agent will automatically use protocol >2 when speaking to compatible agents)
2014-02-08 00:41:03 +00:00
```
2016-08-16 21:15:13 +00:00
This says the version of Consul as well as the protocol versions this
2016-08-17 18:29:09 +00:00
agent speaks and can understand.
2016-08-16 21:15:13 +00:00
2016-11-25 16:00:02 +00:00
Sometimes Consul will default to speak a lower protocol version
2016-08-16 21:15:13 +00:00
than it understands, in order to ease compatibility with older agents. For
example, Consul agents that understand version 3 claim to speak version 2,
and only send version 3 messages to agents that understand version 3. This
allows features to upshift automatically as agents are upgraded, and is the
strategy used whenever possible. If this is not possible, then you will need
to do a backward incompatible upgrade using the instructions above, and such
a requirement will be clearly outlined in the notes for a given release.
2014-02-08 00:41:03 +00:00
2014-02-19 01:37:23 +00:00
By specifying the `-protocol` flag on `consul agent` , you can tell the
Consul agent to speak any protocol version that it can understand. This
only specifies the protocol version to _speak_ . Every Consul agent can
2014-02-08 00:41:03 +00:00
always understand the entire range of protocol versions it claims to
2014-02-19 01:37:23 +00:00
on `consul -v` .
2014-02-08 00:41:03 +00:00
2014-10-19 23:40:10 +00:00
~> **By running a previous protocol version** , some features
2014-02-19 01:37:23 +00:00
of Consul, especially newer features, may not be available. If this is the
case, Consul will typically warn you. In general, you should always upgrade
2014-02-08 00:41:03 +00:00
your cluster so that you can run the latest protocol version.
