github.com/outbrain/consul@v1.4.5/website/source/docs/upgrading.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Upgrading Consul"
     4  sidebar_current: "docs-upgrading-upgrading"
     5  description: |-
     6    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.
     7  ---
     8  
     9  # Upgrading Consul
    10  
    11  Consul is meant to be a long-running agent on any nodes participating in a
    12  Consul cluster. These nodes consistently communicate with each other. As such,
    13  protocol level compatibility and ease of upgrades is an important thing to
    14  keep in mind when using Consul.
    15  
    16  This page documents how to upgrade Consul when a new version is released.
    17  
    18  ## Standard Upgrades
    19  
    20  For upgrades we strive to ensure backwards compatibility. To support this,
    21  nodes gossip their protocol version and builds. This enables clients and
    22  servers to intelligently enable new features when available, or to gracefully
    23  fallback to a backward compatible mode of operation otherwise.
    24  
    25  For most upgrades, the process is simple. Assuming the current version of
    26  Consul is A, and version B is released.
    27  
    28  1. Check the [version's upgrade notes](/docs/upgrade-specific.html) to ensure
    29     there are no compatibility issues that will affect your workload. If there
    30     are plan accordingly before continuing.
    31  
    32  2. On each server, install version B of Consul.
    33  
    34  3. One server at a time, shut down version A, restart with version B. Wait until
    35     the server is healthy and has rejoined the cluster before moving on to the
    36     next server.
    37  
    38  4. Once all the servers are upgraded, begin a rollout of clients following
    39     the same process.
    40  
    41  5. Done! You are now running the latest Consul agent. You can verify this
    42     by running `consul members` to make sure all members have the latest
    43     build and highest protocol version.
    44  
    45  
    46  ## Backward Incompatible Upgrades
    47  
    48  In some cases, a backwards incompatible update may be released. This has not
    49  been an issue yet, but to support upgrades we support setting an explicit
    50  protocol version. This disables incompatible features and enables a 2-phase upgrade.
    51  
    52  For the steps below, assume you're running version A of Consul, and then
    53  version B comes out.
    54  
    55  1. On each node, install version B of Consul.
    56  
    57  2. One server at a time, shut down version A, and start version B with the
    58     `-protocol=PREVIOUS` flag, where "PREVIOUS" is the protocol version of
    59     version A (which can be discovered by running `consul -v` or `consul
    60     members`). Wait until the server is healthy and has rejoined the cluster
    61     before moving on to the next server.
    62  
    63  3. Once all nodes are running version B, go through every node and restart the
    64     version B agent _without_ the `-protocol` flag, again wait for each server to
    65     rejoin the cluster before continuing.
    66  
    67  4. Done! You're now running the latest Consul agent speaking the latest protocol.
    68     You can verify this is the case by running `consul members` to
    69     make sure all members are speaking the same, latest protocol version.
    70  
    71  The key to making this work is the [protocol compatibility](/docs/compatibility.html)
    72  of Consul. The protocol version system is discussed below.
    73  
    74  ## Protocol Versions
    75  
    76  By default, Consul agents speak the latest protocol they can. However, each
    77  new version of Consul is also able to speak the previous protocol, if there
    78  were any protocol changes.
    79  
    80  You can see what protocol versions your version of Consul understands by
    81  running `consul -v`. You'll see output similar to that below:
    82  
    83  ```
    84  $ consul -v
    85  Consul v0.7.0
    86  Protocol 2 spoken by default, understands 2 to 3 (agent will automatically use protocol >2 when speaking to compatible agents)
    87  ```
    88  
    89  This says the version of Consul as well as the protocol versions this
    90  agent speaks and can understand.
    91  
    92  Sometimes Consul will default to speak a lower protocol version
    93  than it understands, in order to ease compatibility with older agents. For
    94  example, Consul agents that understand version 3 claim to speak version 2,
    95  and only send version 3 messages to agents that understand version 3. This
    96  allows features to upshift automatically as agents are upgraded, and is the
    97  strategy used whenever possible. If this is not possible, then you will need
    98  to do a backward incompatible upgrade using the instructions above, and such
    99  a requirement will be clearly outlined in the notes for a given release.
   100  
   101  By specifying the `-protocol` flag on `consul agent`, you can tell the
   102  Consul agent to speak any protocol version that it can understand. This
   103  only specifies the protocol version to _speak_. Every Consul agent can
   104  always understand the entire range of protocol versions it claims to
   105  on `consul -v`.
   106  
   107  ~> **By running a previous protocol version**, some features
   108  of Consul, especially newer features, may not be available. If this is the
   109  case, Consul will typically warn you. In general, you should always upgrade
   110  your cluster so that you can run the latest protocol version.