Upgrade Consul to v2.0.x

Upgrade a Consul Enterprise datacenter to v2.0.x from Consul Enterprise 1.21.7 or later. Before you upgrade, the datacenter must run an IBM Consul Enterprise license. You upgrade server agents one at a time, then client and snapshot agents. No configuration changes are required unless you run Consul API Gateway on Kubernetes.

If you run a version earlier than Consul Enterprise 1.21.7, upgrade to the 1.21.x long-term support (LTS) release first. Review the version-specific upgrade details for each major version between your current release and 1.21.x to plan an intermediate upgrade path.

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.

Requirements

• All Consul servers, clients, and agents running the snapshot role 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 access control lists (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 discovery chain: Consul 2.0.x enables the API gateway discovery chain by default. This capability is not yet mature and is not feature-gated, so evaluate it carefully before you use it in production. Behavior can change in later releases. Consul 1.22.x does not include the API gateway discovery chain, and Consul 2.1.x includes it but does not enable it. Consul 2.0.x gateways also lack API gateway options added in Consul 2.1, such as http2 and grpc listener protocols, header match inversion, and passive health checks. Refer to API gateway features that require a completed upgrade for details. If you run API gateways, upgrade directly to Consul 2.1.x instead of 2.0.x when your upgrade path allows it.
• 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

1. 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.

2. Confirm every server, client, and agent running the snapshot role 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
   

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 agents running the snapshot role 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.