HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul Home

Upgrade Consul to v2.0.x

The page describes the process to update a Consul deployment to v2.0.x.

Introduction

This guide explains how to upgrade a Consul Enterprise datacenter to the latest v2.0.x release from Consul Enterprise 1.21.x (LTS). If you are on an earlier major version, you must first upgrade to Consul Enterprise 1.21.x before continuing with this guide. Review the version-specific upgrade details for each major version between your current release and 1.21.x to plan an intermediate upgrade path.

If you have multiple Consul datacenters, upgrade them in the normal order and take the following instructions into account for each upgrade.

For Consul Community Edition, follow the General Upgrade Process. Community Edition is not affected by the Enterprise licensing prerequisite described below, but does not have access to Enterprise-only features introduced in 2.0.x, such as multi-port service mesh routing.

You can only upgrade to Consul Enterprise 2.0.x from Consul Enterprise 1.21.7 or later, running an IBM Consul Enterprise license. If you still use a HashiCorp-issued license, you must first complete the license migration process on Consul Enterprise 1.21.7 or later before upgrading to 2.0.x. Attempting to upgrade directly to 2.0.x with a HashiCorp-issued license, or from a version earlier than 1.21.7, can cause agents to fail to start.

Requirements

  • All Consul servers, clients, and snapshot agents should be on Consul Enterprise version >= 1.21.7 and < 2.0.0. If they are not at the minimum version, follow the normal upgrade procedures to upgrade them until the version requirement is met.
  • Your Consul Enterprise cluster must already use an IBM Consul Enterprise license. Refer to Upgrade to IBM Consul Enterprise license.

Assumptions

This guide makes the following assumptions:

  • You are familiar with the General Upgrade Process.
  • You have the ability to run Consul CLI commands.
  • If ACLs are in use, then you possess a token with at least operator:read permissions.
  • If you run Consul API Gateway on Kubernetes, you are prepared to migrate Gateway API resources as part of this upgrade.

Considerations

The changes outlined on the Consul 2.0.x version-specific upgrade details page are the main changes in Consul 2.0.x that require special handling during the upgrade process. Review the changes prior to upgrading, in particular:

  • Versioning scheme change: Consul 2.0.0 changes the release versioning format from semantic versioning (X.Y.Z) to IBM's Version-Modification-Fix (V.M.F) model. This does not require configuration changes but affects how you plan future upgrades.
  • Multi-port service mesh routing is Enterprise-only: If you plan to use multi-port services, refer to multi-port services for configuration details.
  • API gateway Kubernetes resource types changed: If you run Consul API Gateway on Kubernetes, especially on OpenShift Container Platform (OCP) 4.19 and later, you must migrate Gateway, HTTPRoute, TCPRoute, and ReferenceGrant resources to the new consul.hashicorp.com resource types. Refer to Upgrade Gateway resource types for step-by-step instructions. Complete this migration as part of the same upgrade window if you run API Gateway on OCP.
  • Opt-in telemetry reporting: Consul 2.0.0 introduces telemetry reporting that is disabled by default. No action is required to preserve existing behavior.

You can also review the full 2.0.0, 2.0.1, 2.0.2, and 2.0.3 changelogs. We strongly recommend reviewing the changes prior to upgrading.

Procedures

Any steps in the following section that mention upgrading servers/clients assume that normal safe upgrade procedures are followed. Refer to our documentation for the basic server upgrade process, and for autopilot assisted upgrades for more information.

1. Confirm every server, client, and snapshot agent in the datacenter is running Consul Enterprise 1.21.7 or later with an IBM Consul Enterprise license applied. Run the following command on a server to confirm the license type:

consul license get

2. Take a snapshot of the cluster by running the following command:

consul snapshot save pre-2-0-upgrade.snap

Run this command from anywhere Consul is already running, or from a location with network access to the cluster. Additional command line options for directing the request to the correct Consul API may be necessary if the command runs from another location. Ensure that there is enough disk space in the current directory to store the snapshot.

This snapshot should not be needed, but if something were to go wrong, having the snapshot would make it possible to restore the previous state.

3. If you run Consul API Gateway on Kubernetes, back up your existing Gateway, HTTPRoute, TCPRoute, and ReferenceGrant resources before upgrading. Refer to Upgrade Gateway resource types for the backup commands and the full migration procedure.

4. Upgrade all server agents to Consul Enterprise 2.0.x, one server at a time, following the basic server upgrade process. Wait for each server to rejoin the cluster and report healthy before continuing to the next.

5. Upgrade all client agents to Consul Enterprise 2.0.x.

6. Upgrade all snapshot agents to Consul Enterprise 2.0.x.

7. If you run Consul API Gateway on Kubernetes, complete the resource migration described in Upgrade Gateway resource types.

8. Confirm the upgrade completed successfully by running the following command to verify that all members report the new version:

consul members

Post-Upgrade Configuration Changes

No configuration changes are required for this upgrade, other than the API gateway Kubernetes resource type migration described above for clusters running Consul API Gateway on Kubernetes.

Edit this page on GitHub