Migrate to Consul dataplane with legacy server compatibility
This topic describes how to upgrade to Consul v1.21.x when your Kubernetes deployment runs Consul v1.18.x, consul-k8s v1.4.x, and Consul dataplane v1.4.x. The -legacy-server-compat flag lets you upgrade the dataplane layer first so that you can progress to Consul v1.21.x without disrupting mesh traffic.
Background
When you prepare to upgrade to Consul v1.21.x from Consul v1.18.x with consul-k8s v1.4.x and Consul dataplane v1.4.x, both standard upgrade paths can block your progress:
- When you upgrade the dataplane first, Consul dataplane v1.8.x runs a startup feature check and refuses to accept servers that do not advertise full dataplane feature support, including the
DATAPLANE_FEATURES_ENVOY_BOOTSTRAP_CONFIGURATIONfeature. - When you upgrade Consul first, the older dataplane lacks the Envoy version that the newer Consul servers require, so mesh traffic stops until you upgrade the dataplane.
The -legacy-server-compat flag provides a temporary compatibility mode that bypasses the dataplane feature check so that you can connect Consul dataplane v1.8.x to Consul v1.18.x servers during the migration to Consul v1.21.x.
Requirements
- consul-dataplane v1.4.x
- consul-k8s v1.4.x
- Consul server agents v1.18.x
Migration paths
Choose a migration path based on whether you need to maintain mesh traffic during the upgrade.
| Path | Mesh traffic | DNS | Pod restarts | Flag required |
|---|---|---|---|---|
| Dataplane-first | Available throughout | Available throughout | 2 | Yes (DP_LEGACY_SERVER_COMPAT) |
| Consul-first | Stops during the Consul upgrade | Available throughout | 1 | No |
During either migration window, central telemetry and merged Prometheus metrics are unavailable.
We recommend the dataplane-first path when you require zero mesh traffic disruption.
Upgrade Consul dataplane from v1.4.x to v1.8.x and enable the compatibility mode. On Kubernetes,
consul-dataplaneis invoked automatically by the connect-injector webhook — do not run the binary manually or usekubectl exec. Deliver the flag as an environment variable on the sidecar container using one of the following methods:- Pod annotation (per-workload, recommended): Add the
consul.hashicorp.com/consul-dataplane-env-varsannotation to each pod that needs compat mode. The connect-injector reads this annotation and injects the listed env vars into theconsul-dataplanesidecar it generates. Use this approach to roll out the flag incrementally and remove it per-pod once migration is complete. - Helm
connectInject.extraEnvironmentVars(cluster-wide): SetDP_LEGACY_SERVER_COMPAT: "true"underconnectInject.extraEnvironmentVarsin yourvalues.yamland apply withhelm upgrade. This sets the flag on every injected pod across the cluster at once. Remove the key and re-apply the chart after migration is complete so the flag does not persist in production.
This step requires a pod restart so that the sidecar restarts with the environment variable set.
- Pod annotation (per-workload, recommended): Add the
Perform a rolling upgrade of Consul from v1.18.x to v1.21.x.
Upgrade consul-k8s from v1.4.x to v1.8.x.
After the servers advertise full dataplane feature support, confirm that the dataplane connects without warnings. When the connected server supports the full dataplane feature set, Consul dataplane lifts the compatibility guards and logs a recommendation to remove the environment variable.
Remove the
DP_LEGACY_SERVER_COMPATenvironment variable (delete the pod annotation or remove theconnectInject.extraEnvironmentVarsentry fromvalues.yaml) and perform a rolling restart of your injected workloads. The dataplane reconnects in normal mode with full feature support. This step requires a pod restart.
Mesh traffic remains available throughout this migration. Central telemetry and merged Prometheus metrics remain disabled until you remove the environment variable.