github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Incorporate changes from engineering review

pull/8678/head
Joel Watson 2020-09-18 15:18:46 -05:00
parent 70ebf306a2
commit 2265ad41be
4 changed files with 46 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
website/pages/docs/upgrading/index.mdx
View File

@ -47,11 +47,11 @@ Consul is A, and version B is released.
## Large Version Jumps ## Large Version Jumps
Operating a Consul datacenter that is multiple major versions behind the current major version can increase the risk incured during Operating a Consul datacenter that is multiple major versions behind the current major
upgrades. We encourage our customers to remain no more than two major versions behind version can increase the risk incurred during upgrades. We encourage our users to
(i.e., if 1.8.x is the current release, do not use versions older than 1.6.x). remain no more than two major versions behind (i.e., if 1.8.x is the current release,
If you find yourself in a situation do not use versions older than 1.6.x). If you find yourself in a situation where you
where you are many major versions behind, and need to upgrade, please review our are many major versions behind, and need to upgrade, please review our
[Upgrade Instructions page](/docs/upgrading/instructions) for information on [Upgrade Instructions page](/docs/upgrading/instructions) for information on
how to perform those upgrades. how to perform those upgrades.

52
website/pages/docs/upgrading/instructions/general-process.mdx
View File

@ -76,8 +76,14 @@ this snapshot somewhere safe. More documentation on snapshot usage is available
- https://learn.hashicorp.com/tutorials/consul/backup-and-restore - https://learn.hashicorp.com/tutorials/consul/backup-and-restore
**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/options.html#_log_level) **2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/options.html#_log_level)
is set to `debug`. After doing this, issue the `consul reload` command on your servers. This will is set to `debug`. After doing this, issue the following command on your servers to
give you more information to work with in the event something goes wrong. reload the configuration:
```
consul reload
```
This change will give you more information to work with in the event something goes wrong.
## Perform the Upgrade ## Perform the Upgrade
@ -101,16 +107,25 @@ Take note of which agent is the leader.
**2.** Copy the new `consul` binary onto your servers and replace the existing **2.** Copy the new `consul` binary onto your servers and replace the existing
binary with the new one. binary with the new one.
**3.** Perform a rolling restart of Consul on your servers, leaving the leader agent **3.** The following steps must be done in order on the server agents, leaving the leader
for last. Only restart one server at a time. After restarting each server, validate agent for last. First force the server agent to leave the cluster with the following command:
that it has rejoined the cluster and is in sync with the leader by issuing the `consul info` command,
and checking whether the `commit_index` and `last_log_index` fields have the same value.
If done properly, this should avoid an unexpected leadership election due to loss of quorum.
~> It is important to issue a `consul leave` command on each server node when shutting ```
Consul down. Make sure your service management system (e.g., systemd, upstart, etc.) is consul leave
performing that action. If not, make sure you do it manually or you _will_ end up in a ```
bad cluster state.
Then, use a service management system (e.g., systemd, upstart, etc.) to restart the Consul service. If
you are not using a service management system, you must restart the agent manually.
To validate that the agent has rejoined the cluster and is in sync with the leader, issue the
following command:
```
consul info
```
Check whether the `commit_index` and `last_log_index` fields have the same value. If done properly,
this should avoid an unexpected leadership election due to loss of quorum.
**4.** Double-check that all servers are showing up in the cluster as expected and are on **4.** Double-check that all servers are showing up in the cluster as expected and are on
the correct version by issuing: the correct version by issuing:
@ -143,13 +158,17 @@ dc1-node2 20e6be1b-f1cb-4aab-929f-f7d2d43d9a96 10.11.0.3:8300 follower true
dc1-node3 658c343b-8769-431f-a71a-236f9dbb17b3 10.11.0.4:8300 follower true 3 dc1-node3 658c343b-8769-431f-a71a-236f9dbb17b3 10.11.0.4:8300 follower true 3
``` ```
**5.** Set your `log_level` back to what you had it at prior to the upgrade and issue **5.** Set your `log_level` back to its original value and issue the following command
`consul reload` again. on your servers to reload the configuration:
```
consul reload
```
## Troubleshooting ## Troubleshooting
Most problems with upgrading occur due to either failing to upgrade the leader agent last, Most problems with upgrading occur due to either failing to upgrade the leader agent last,
or due to failing to wait for a follower agent to fully rejoin a cluster before moving or failing to wait for a follower agent to fully rejoin a cluster before moving
on to another server. This can cause a loss of quorum and occasionally can result in on to another server. This can cause a loss of quorum and occasionally can result in
all of your servers attempting to kick off leadership elections endlessly without ever all of your servers attempting to kick off leadership elections endlessly without ever
reaching a quorum and electing a leader. reaching a quorum and electing a leader.
@ -157,13 +176,12 @@ reaching a quorum and electing a leader.
Most of these problems can be solved by following the steps outlined in our Most of these problems can be solved by following the steps outlined in our
[Outage Recovery](https://learn.hashicorp.com/tutorials/consul/recovery-outage) document. [Outage Recovery](https://learn.hashicorp.com/tutorials/consul/recovery-outage) document.
If you are still having trouble after trying the recovery steps outlined there, If you are still having trouble after trying the recovery steps outlined there,
then these options for further assistance are available: then the following options for further assistance are available:
- OSS users without paid support plans can request help in our [Community Forum](https://discuss.hashicorp.com/c/consul/29) - OSS users without paid support plans can request help in our [Community Forum](https://discuss.hashicorp.com/c/consul/29)
- Enterprise and OSS users with paid support plans can contact [HashiCorp Support](https://support.hashicorp.com/) - Enterprise and OSS users with paid support plans can contact [HashiCorp Support](https://support.hashicorp.com/)
If you end up contacting support, please make sure you include the following information When contacting Hashicorp Support, please include the following information in your ticket:
in your support ticket:
- Consul version you were upgrading FROM and TO. - Consul version you were upgrading FROM and TO.
- [Debug level logs](/docs/agent/options.html#_log_level) from all servers in the cluster - [Debug level logs](/docs/agent/options.html#_log_level) from all servers in the cluster

7
website/pages/docs/upgrading/instructions/index.mdx
View File

@ -9,7 +9,7 @@ description: >-
# Upgrade Instructions # Upgrade Instructions
This document is intended to help customers who find themselves many versions behind to upgrade safely. This document is intended to help users who find themselves many versions behind to upgrade safely.
Our recommended upgrade path is moving from version 0.8.5 to 1.2.4 to 1.6.9 to the current version. To get Our recommended upgrade path is moving from version 0.8.5 to 1.2.4 to 1.6.9 to the current version. To get
started, you will want to choose the version you are currently on below and then follow the instructions started, you will want to choose the version you are currently on below and then follow the instructions
until you are on the latest version. The upgrade guides will mention notable changes and link to relevant until you are on the latest version. The upgrade guides will mention notable changes and link to relevant
@ -31,4 +31,7 @@ To get instructions for your upgrade, please choose the release series you are _
- [1.6.x](/docs/upgrading/instructions/upgrade-to-1-8-x) - [1.6.x](/docs/upgrading/instructions/upgrade-to-1-8-x)
- [1.7.x](/docs/upgrading/instructions/upgrade-to-1-8-x) - [1.7.x](/docs/upgrading/instructions/upgrade-to-1-8-x)
If you are using <= 0.7.x, please [contact support](https://support.hashicorp.com) for assistance. If you are using <= 0.7.x, please contact support for assistance:
- OSS users without paid support plans can request help in our [Community Forum](https://discuss.hashicorp.com/c/consul/29)
- Enterprise and OSS users with paid support plans can contact [HashiCorp Support](https://support.hashicorp.com/)

2
website/pages/docs/upgrading/instructions/upgrade-to-1-6-x.mdx
View File

@ -56,7 +56,7 @@ Two very notable items are:
## Procedure ## Procedure
**1.** Check replication status in DC1 by issuing the following curl command from a **1.** Check the replication status of the primary datacenter (DC1) by issuing the following curl command from a
consul server in that DC: consul server in that DC:
```shell ```shell