From 6d43b8cb6cfdcaf0fc631849f013ed40f337f4ec Mon Sep 17 00:00:00 2001 From: Armon Dadgar Date: Wed, 11 Jun 2014 11:25:55 -0700 Subject: [PATCH] website: Clarify upgrade procedures. Fixes #187. --- .../source/docs/compatibility.html.markdown | 6 ++-- website/source/docs/upgrading.html.markdown | 32 +++++++++++++++++-- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/website/source/docs/compatibility.html.markdown b/website/source/docs/compatibility.html.markdown index de7904a4c8..05ef601a89 100644 --- a/website/source/docs/compatibility.html.markdown +++ b/website/source/docs/compatibility.html.markdown @@ -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 diff --git a/website/source/docs/upgrading.html.markdown b/website/source/docs/upgrading.html.markdown index 18171c23f9..fdac5ff96e 100644 --- a/website/source/docs/upgrading.html.markdown +++ b/website/source/docs/upgrading.html.markdown @@ -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.