#Migrating a single-cluster mesh

The phases below migrate a mesh that runs in one cluster. A mesh that spans several clusters follows the same phases with additional steps, see Migrating a multi-cluster mesh.

Run the phases in order. Each one ends with checks that must pass before the next one starts.

1. Preparing for the migration — Phase 0. Check the cluster, record the Mesh v1 configuration, back everything up, start the probes. Nothing changes yet.
2. Installing the Mesh v2 control plane — Phase 1 and Phase 2. Install Kiali and the metrics resources, then create IstioCNI and Istio next to Mesh v1. Workloads are untouched, and both resources can be deleted to roll back.
3. Migrating workloads — Phase 3. Move namespaces and workloads to the Mesh v2 revision one at a time. Each move can be reversed.
4. Migrating gateways — Phase 4. Run a Mesh v2 gateway next to each Mesh v1 gateway and shift traffic to it. The Mesh v1 gateway stays in place, scaled to zero, until Phase 5.
5. Decommissioning Mesh v1 — Phase 5. Remove Mesh v1 by hand. This phase cannot be rolled back: afterwards, recovery means reinstalling Mesh v1 from the backups.
6. Finalizing the migration and Migrating the observability stack — Phase 6. Adopt the default revision tag, hand over the certificate authority, and move tracing to OpenTelemetry v2 and Jaeger v2.

Mesh v2 reads the Istio resources of your mesh as they are, but not the Mesh v1 resources that configure the mesh itself. Whatever you changed in the Mesh v1 control plane has to be expressed the Mesh v2 way before the workloads move, see Collect the custom Istio configuration.

See Rolling back the migration for what each phase can be rolled back to, and Troubleshooting the migration for the problems reported most often.