Upgrade clusters on HCP Consul

This topic describes the process to upgrade a cluster's version on HCP Consul. HCP provides a dedicated workflow to upgrade the version of a HashiCorp-managed cluster. You can also view the current versions of self-managed clusters that are linked to HCP Consul to help you manage versions across your deployment.

For more general information about the upgrade process, refer to Upgrading Consul in the Consul documentation.

Introduction

As described in the Consul documentation, the general upgrade process for Consul servers consists of the following steps:

Create a snapshot of your cluster. If an error occurs during the upgrade process, this snapshot can be used to recover the servers' previous working state.
Check the current state of the Raft quorum to find the cluster's leader. Upgrade the binary on the followers first, then upgrade the leader.

You can use HCP to simplify the process of managing Consul versions for both HashiCorp-managed and self-managed clusters. When a new version of Consul in released, a badge appears in the Consul overview to inform you if your cluster is out of date or out of support. You can upgrade the cluster's version at a time of your choosing, according to your network's needs.

You can upgrade as new versions of Consul become available or as your networking needs evolve. HashiCorp may upgrade the base host image or version used by your Consul clusters to fix some common vulnerabilities and exposures (CVE).

Cluster versions

To safely and securely manage your Consul clusters, HCP Consul follows HashiCorp’s Support Period Policy. Be aware of the following aspects of the policy:

HCP Consul offers n-2 version support for bug fixes and CVEs via new minor releases, where n is the latest major release of Consul. You can identify a major release by a change in the first digit (X) or the second digit (Y) of the Consul version nomenclature (X.Y.Z). For example, if the latest release is 1.16.*, fixes will be available for versions 1.16.*, 1.15.*, and 1.14.*.
HashiCorp updates HashiCorp-managed Consul clusters with CVE patches for clusters that fall within the n-2 version.
HashiCorp recommends users keep Consul clusters within two (2) major releases from the latest major release. Doing so ensures that bug fixes and security patches are successfully applied to HashiCorp-managed clusters.
HashiCorp supports Generally Available (GA) Consul releases for up to two years from their release date. In some cases, HashiCorp may request that users upgrade to newer releases in order to resolve support requests.

Upgrade HashiCorp-managed cluster's Consul version

Warning

Before you upgrade a Consul, we recommend creating a snapshot of the cluster. If an error occurs or your service network does not function as expected, use the snapshot to restore your cluster to its last working state.

Sign in to the HCP Portal.
Select the organization or project where you created the cluster.
Click Consul.
From the Consul Overview, next to the snapshot you want toupdate, click More (three horizontal dots) and then Update version.
Select a version from the dropdown. Then, click Update now.

The cluster's status changes to Updating as the process takes place.

Upgrade self-managed cluster's Consul version

When self-managed clusters are linked to HCP Consul, their version number appears next to the cluster in the Consul overview. Consul also displays a badge to alert you when a self-managed cluster is running an outdated version of Consul. However, automatic version upgrades through HCP are not supported for self-managed clusters.

The following options are available to upgrade self-managed cluster:

Enterprise users can configure automated upgrades on their self-managed servers using the Autopilot feature.
Kubernetes deployments can upgrade using the consul-k8s CLI.

Refer to Upgrading Consul for more information on the upgrade process, including how to upgrade across large version jumps.

Upgrade self-managed cluster with `consul-k8s`

If you use the Consul on Kubernetes CLI with your self-managed cluster, you can follow a simplified process to upgrade your Consul version. Complete the following steps to upgrade a cluster that is already linked to HCP Consul:

Retrieve the cluster's configuration.
```
$ consul-k8s status
```
Copy the configuration into a YAML file then update it to your desired configuration. The following example updates the Consul version to 1.14.3.
```
global:
-  image: consul:1.14.2
+  image: consul:1.14.3
```
Run the consul-k8s CLI upgrade command.
```
$ consul-k8s upgrade -f values.yaml
```

Refer to the Helm chart reference for more information about configuration values. To get started with the consul-k8s CLI, refer to Install Consul on Kubernetes from Consul K8s CLI.