website: Clarify upgrade procedures. Fixes #187.

This commit is contained in:
Armon Dadgar 2014-06-11 11:25:55 -07:00
parent d48379054b
commit 2d106f9765
2 changed files with 32 additions and 6 deletions

View File

@ -15,10 +15,10 @@ We promise that every subsequent release of Consul will remain backwards
compatible with _at least_ one prior version. Concretely: version 0.5 can
speak to 0.4 (and vice versa), but may not be able to speak to 0.1.
The backwards compatibility must be explicitly enabled: Consul agents by
default will speak the latest protocol, but can be configured to speak earlier
The backwards compatibility is automatic unless otherwise noted. Consul agents by
default will speak the latest protocol, but can understand earlier
ones. If speaking an earlier protocol, _new features may not be available_.
The ability for an agent to speak an earlier protocol is only so that they
The ability for an agent to speak an earlier protocol is so that they
can be upgraded without cluster disruption.
This compatibility guarantee makes it possible to upgrade Consul agents one

View File

@ -13,10 +13,36 @@ keep in mind when using Consul.
This page documents how to upgrade Consul when a new version is released.
## Upgrading Consul
## Standard Upgrades
In short, upgrading Consul is a short series of easy steps. For the steps
below, assume you're running version A of Consul, and then version B comes out.
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.
1. On each node, install version B of Consul.