mirror of https://github.com/hashicorp/consul
133 lines
4.8 KiB
Plaintext
133 lines
4.8 KiB
Plaintext
|
---
|
|||
|
|
layout: docs
|
|||
|
|
page_title: Upgrading to 1.2.4
|
|||
|
|
sidebar_title: Upgrading to 1.2.4
|
|||
|
|
description: >-
|
|||
|
|
Specific versions of Consul may have additional information about the upgrade
|
|||
|
|
process beyond the standard flow.
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Upgrading to 1.2.4
|
|||
|
|
|
|||
|
|
## Introduction
|
|||
|
|
|
|||
|
|
This guide explains how to best upgrade a multi-datacenter Consul deployment that's using
|
|||
|
|
a version of Consul >= 0.8.5 and < 1.2.4 while maintaining replication. If you're on a version
|
|||
|
|
older than 0.8.5, but are in the 0.8.x series, please upgrade to 0.8.5 by following our
|
|||
|
|
[General Upgrade Process](/docs/upgrading/instructions/general-process). If you're on a version
|
|||
|
|
older than 0.8.0, please [contact support](https://support.hashicorp.com). As there weren't
|
|||
|
|
any major breaking changes, this upgrade shoul be fairly simple.
|
|||
|
|
|
|||
|
|
In this guide, we'll be using an example with two datacenters (DCs) and will be
|
|||
|
|
referring to them as DC1 and DC2. DC1 will be the primary datacenter.
|
|||
|
|
|
|||
|
|
## Requirements
|
|||
|
|
|
|||
|
|
- All Consul servers should be on a version of Consul >= 0.8.5 and < 1.2.4.
|
|||
|
|
- You need a Consul cluster with at least 3 nodes to perform this upgrade as documented. If
|
|||
|
|
you either have a single node cluster or several single node clusters joined via WAN, the
|
|||
|
|
servers will come up in a `No cluster leader` loop after upgrading. If that happens, you'll
|
|||
|
|
need to recover the cluster using the method described [here](https://learn.hashicorp.com/tutorials/consul/recovery-outage#manual-recovery-using-peers-json).
|
|||
|
|
You can avoid this issue entirely by growing your cluster to 3 nodes prior to upgrading.
|
|||
|
|
|
|||
|
|
## Assumptions
|
|||
|
|
|
|||
|
|
This guides makes the following assumptions:
|
|||
|
|
|
|||
|
|
- You have at least two datacenters configured and have ACL replication enabled. If you're
|
|||
|
|
not using multiple datacenters, you can follow along and simply skip the instructions related
|
|||
|
|
to replication.
|
|||
|
|
|
|||
|
|
## Considerations
|
|||
|
|
|
|||
|
|
There aren't too many major changes that might cause issues upgrading from 1.0.8, but notable changes
|
|||
|
|
are called out in our [Specific Version Details](/docs/upgrading/upgrade-specific#consul-1-1-0)
|
|||
|
|
page. You can find more granular details in the full [changelog](https://github.com/hashicorp/consul/blob/master/CHANGELOG.md#124-november-27-2018).
|
|||
|
|
Looking through these changes prior to upgrading is highly recommended.
|
|||
|
|
|
|||
|
|
## Procedure
|
|||
|
|
|
|||
|
|
**1.** Check replication status in DC1 by running the following curl command from a
|
|||
|
|
consul server in that DC:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
curl -s -H "X-Consul-Token: $MASTER_TOKEN" localhost:8500/v1/acl/replication?pretty
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
You should see output that looks like this:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"Enabled": false,
|
|||
|
|
"Running": false,
|
|||
|
|
"SourceDatacenter": "",
|
|||
|
|
"ReplicatedIndex": 0,
|
|||
|
|
"LastSuccess": "0001-01-01T00:00:00Z",
|
|||
|
|
"LastError": "0001-01-01T00:00:00Z"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
-> The primary datacenter (indicated by `acl_datacenter`) will always show as having replication
|
|||
|
|
disabled, so this is normal even if replication is happening.
|
|||
|
|
|
|||
|
|
**2.** Check replication status in DC2 by running the following curl command from a
|
|||
|
|
consul server in that DC:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
curl -s -H "X-Consul-Token: $MASTER_TOKEN" localhost:8500/v1/acl/replication?pretty
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
You should see output that looks like this:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"Enabled": true,
|
|||
|
|
"Running": true,
|
|||
|
|
"SourceDatacenter": "dc1",
|
|||
|
|
"ReplicatedIndex": 9,
|
|||
|
|
"LastSuccess": "2020-09-10T21:16:15Z",
|
|||
|
|
"LastError": "0001-01-01T00:00:00Z"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**3.** Upgrade the Consul agents in all DCs to version 1.2.4 by following our [General Upgrade Process](/docs/upgrading/instructions/general-process).
|
|||
|
|
This should be done one DC at a time, leaving the primary DC for last.
|
|||
|
|
|
|||
|
|
**4.** Confirm that replication is still working in DC2 by running the following curl command from a
|
|||
|
|
consul server in that DC:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
curl -s -H "X-Consul-Token: $MASTER_TOKEN" localhost:8500/v1/acl/replication?pretty
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
You should see output that looks like this:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"Enabled": true,
|
|||
|
|
"Running": true,
|
|||
|
|
"SourceDatacenter": "dc1",
|
|||
|
|
"ReplicatedIndex": 9,
|
|||
|
|
"LastSuccess": "2020-09-10T21:16:15Z",
|
|||
|
|
"LastError": "0001-01-01T00:00:00Z"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Post-Upgrade Configuration Changes
|
|||
|
|
|
|||
|
|
If you moved from a pre-1.0.0 version of Consul, you'll find that _many_ of the configuration
|
|||
|
|
options were renamed. Backwards compatibility has been maintained, so your old config options
|
|||
|
|
will continue working after upgrading, but you'll want to update those now to avoid issues when
|
|||
|
|
moving to newer versions.
|
|||
|
|
|
|||
|
|
You can find the full list of changes here:
|
|||
|
|
|
|||
|
|
- https://www.consul.io/docs/upgrading/upgrade-specific#deprecated-options-have-been-removed
|
|||
|
|
|
|||
|
|
You can make sure your config changes are valid by copying your existing configuration files,
|
|||
|
|
making the changes, and then verifing them by running `consul validate $CONFIG_FILE1_PATH $CONFIG_FILE2_PATH ...`.
|
|||
|
|
|
|||
|
|
Once your config is passing the validation check, replace your old config files with the new ones
|
|||
|
|
and slowly roll your cluster again one server at a time – leaving the leader agent for last in each
|
|||
|
|
datacenter.
|