Upgrading HashiCorp Consul from 1.14, 1.15 or 1.16: Upgrade Path, Version Notes, Envoy, Server Order and Rollback

The short answer

Consul upgrades are rolling and usually uneventful one step at a time. The difficulty with an old cluster is the number of steps. HashiCorp's upgrade instructions say that, outside Consul Enterprise LTS releases, each upgrade should jump at most two major versions. Consul counts 1.15, 1.16 and so on as major versions. A Community Edition cluster on 1.15 therefore needs four hops to reach 2.0, and each hop has its own version-specific notes.

The support picture on 5 October 2026. The LTS, 1.22 and 2.0 dates come from HashiCorp's Consul Enterprise support page; standard releases are maintained for roughly a year, so the older standard lines are already out:

For Community Edition, HashiCorp's guidance is that staying on a maintained version means upgrading to the latest major release every four months. Today that is 2.0. The Consul end-of-life tracker has every line, and Consul on an end-of-life version covers the support and licence choices in more depth. This guide is about doing the upgrade.

The licence line you cross

HashiCorp moved Consul to the Business Source License 1.1 at 1.17.0, and the 2.0 licence names IBM as licensor and "Consul Version 1.17.0 or later" as the licensed work. Later patch releases on the older branches were relicensed too: the LICENSE files in later tags name 1.15.8 and later, and 1.16.4 and later, as BSL. So the last MPL 2.0 releases are 1.15.7 and 1.16.3.

Any upgrade from 1.16.3 to a maintained release moves the cluster onto BSL terms. The BSL's additional use grant permits production use unless you offer Consul to third parties on a hosted or embedded basis to compete with IBM's paid versions. Most internal platform teams are not affected, but read the grant before the upgrade if Consul is part of a product you sell or host for customers.

Plan the upgrade path

From the upgrade instructions, the rules are:

• Community Edition: at most two major versions per jump, reviewing the version-specific notes for every version you pass through.
• Consul Enterprise LTS: at most three major versions, from one LTS release to the next, so 1.15 to 1.18 and 1.18 to 1.21.
• Enterprise to 2.0: every server, client and snapshot agent must be on Consul Enterprise 1.21.7 or later with an IBM Consul Enterprise licence. A HashiCorp-issued licence makes 2.0 agents fail to start.
• Very old clusters: dedicated instructions cover 0.8.5 to 1.2.4, 1.2.4 to 1.6.10, 1.6.9 to 1.8.19 and 1.8.0 to 1.10.12.

These paths are our reading of the two-version and LTS rules; other combinations satisfy them too. Use the latest patch release at each hop. If you run the service mesh, choose hops with Envoy in mind, as below.

Version-specific notes that matter from 1.14 up

Clusters older than 1.14 have two further hard stops in the notes: Consul 1.9 supports only Raft protocol 3, so any server configured with raft_protocol = 2 must change first, and 1.11 removed the legacy ACL system deprecated in 1.4.

Envoy and the service mesh

Each Consul release supports a fixed set of Envoy versions, and the general upgrade process says to restart each client agent's Envoy proxies with a compatible version straight after the agent itself. From HashiCorp's compatibility table:

Two consequences. First, no Envoy version is compatible with both 1.20 and 1.21 or later, so the hop onto 1.21, 1.22 or 2.0 always changes Envoy on every node. Second, a mesh upgrade is really a Consul and Envoy upgrade, so Envoy images, sidecar injection and gateway deployments have to be versioned in step. On Kubernetes, Consul dataplane images package Envoy, and each Consul release supports the previous and next dataplane versions.

Before the first server

1. Snapshot. consul snapshot save backup.snap, then consul snapshot inspect backup.snap to confirm the Raft index was captured. Store it off the cluster.
2. Raise the log level on the servers to debug and consul reload, as the general upgrade process recommends.
3. Enterprise only: disable autopilot's upgrade migration with consul operator autopilot set-config -disable-upgrade-migration=true. HashiCorp warns that otherwise a node on the new version may become leader before the existing leader is upgraded.
4. Record the leader with consul operator raft list-peers.

Rolling the servers and clients

1. Install the new binary on every server.
2. Restart the followers first, one at a time, and the leader last.
3. After each restart, run consul info on that server and wait until commit_index and last_log_index match before moving on.
4. When all servers are done, check consul members shows every server alive on the new build, and consul operator raft list-peers shows a leader and the expected voters.
5. Roll the client agents the same way, restarting each node's Envoy proxies on a compatible version after its agent.
6. Return the log level to normal and consul reload.

HashiCorp's troubleshooting section names the two usual causes of failed upgrades: not upgrading the leader last, and not waiting for a follower to rejoin before moving to the next server. Both can lose quorum and leave servers electing leaders endlessly. In a multi-datacenter setup, upgrade one datacenter at a time; HashiCorp has a separate tutorial for federated datacenters, and Kubernetes clusters follow the Consul on Kubernetes upgrade page.

Autopilot upgrade migrations (Enterprise)

Consul Enterprise has a second way to upgrade, on by default. You add new servers on the new version, they join as non-voters, and once there are enough of them to form a quorum autopilot promotes them, triggers an election, and demotes the old servers, which you then remove with consul leave. UpgradeVersionTag lets autopilot read the version from a node_meta tag instead of the binary version. This suits immutable infrastructure. For in-place upgrades, follow HashiCorp's advice and turn the feature off while you roll.

Test plan

• Restore the production snapshot into a staging cluster and run every hop there.
• Check service registration, health checks and DNS queries from a sample of client nodes after each hop.
• Exercise every token type and policy your applications use, including after the 1.16 change to health endpoint status codes.
• Test mesh traffic through sidecars, ingress, terminating and mesh gateways, and every L7 intention with path matching.
• Check cluster peering and WAN federation links in both directions.
• Check every system that coordinates through Consul, such as Patroni locks, Vault storage or Nomad, against the new version.
• Restart a follower and then the leader under load and confirm a clean election.

Rollback

HashiCorp's upgrade guides describe the snapshot as the fallback and stop there; they document no downgrade procedure. Our approach follows from that:

• During the server roll, a follower that will not rejoin can be returned to the previous binary while the leader is still on the old version. Keep the previous binary on every host.
• After the leader has moved, we treat the snapshot as the way back: rebuild the servers on the old version and run consul snapshot restore, accepting that catalogue, KV and ACL changes since the snapshot are lost. Take a new snapshot immediately before each hop, not only at the start.
• Hold back new features, such as templated ACL policies, new config entry kinds or multi-port services, until the hop has settled, since older servers may not understand them.

If you cannot upgrade, or do not want the BSL

Some clusters stay on 1.16.3 or earlier because the licence matters, not because the upgrade is hard. For those, OSSeva ships patched, signed builds on the MPL 2.0 source, 1.16.3 and earlier, rebuilt on a supported Go toolchain with patched dependencies, covering server and client agents, delivered as binaries, Docker images and packages. OSSeva does not redistribute modified BSL code, so for 1.17 and later the route is a supported upgrade to a maintained release, or a migration of coordination to etcd or Kubernetes where that fits better. Assure adds a version and licence inventory across every datacenter, an ACL, gossip encryption and TLS audit, a map of every system coordinating through Consul, a SOC 2 and HIPAA attestation package and an upgrade or migration plan for 1.17 and later clusters. Operate adds 24/7 Raft leadership, peer and autopilot health monitoring, a 15-minute P1 response, a named senior Consul engineer, scheduled snapshots with tested restores, and rolling upgrade execution with Raft quorum preserved. See Consul extended support, HashiCorp Consul support, the Consul 1.18 and Consul 1.22 end-of-life pages and ZooKeeper, etcd, Consul and KRaft compared.

Common questions

Can I upgrade Consul 1.15 straight to 2.0?

No. Community Edition can jump at most two major versions per upgrade. Consul Enterprise LTS can go 1.15 to 1.18 to 1.21, then to 2.0 from 1.21.7 or later with an IBM licence.

Which Consul versions are open source under MPL 2.0?

Releases up to 1.16.3, and 1.15 up to 1.15.7. The licence files name 1.17.0 and later, 1.16.4 and later, and 1.15.8 and later as BSL.

Should I upgrade Consul servers or clients first?

Servers first, followers before the leader, then clients. From 1.19, servers filter health results, so servers-first is required to avoid returning unhealthy instances.

Do I need to upgrade Envoy when I upgrade Consul?

If you run the service mesh, yes, whenever your Envoy version is outside the new release's compatible set. Moving from 1.20 or earlier to 1.21 or later always needs a new Envoy.

Can I roll back a Consul upgrade?

HashiCorp documents a pre-upgrade snapshot as the fallback, not a downgrade. Restoring it on the old version loses changes made since the snapshot.