Upgrade plans
Plan a Kuma or Kong Mesh upgrade with kuma-migrator, from the next 2.x minor to 3.0, and read the report sections that drive it.
kuma-migrator does not upgrade control planes. It tells you which manifests must change
before, during and after an upgrade, writes the changed manifests, and lists what to delete.
This page puts those outputs in the order an upgrade needs them.
Supported upgrade paths
Kuma and Kong Mesh support upgrades of at most two minor versions at a time. The same rule
applies between kuma-dp and kuma-cp, between Zone and Global control planes, and to the
data in the store (Kuma upgrades,
Kong Mesh upgrade).
| From | Path |
|---|---|
| 2.8 | 2.8 → 2.10 → 2.12 → 2.14 → 3.0 |
| 2.9 | 2.9 → 2.11 → 2.13 → 2.14 → 3.0 |
| 2.12 | 2.12 → 2.14 → 3.0 |
| 2.13 LTS | 2.13 → 2.14 → 3.0 |
Latest releases as of 2026-10-30: Kuma 3.0.1 and Kong Mesh 3.0.1, with 2.14.7 and 2.13.12 (LTS) patch releases.
Reach the latest 2.14 patch before 3.0. Several preparation steps need it:
MeshOpenTelemetryBackend exists from 2.14, MeshExternalService accepts the 3.0
SecureDataSource shape from 2.14.6
(Upgrade to 2.14.6),
and Kong Mesh's latest 2.14 patch accepts the renamed KDS authentication settings
(Kong Mesh upgrade notes).
3.0 also changes the supported topology. Check these before planning manifest work:
| Change | Action | Source |
|---|---|---|
| A Kubernetes-native Global control plane is not supported | Move the Global control plane to Universal with a PostgreSQL store before upgrading | Kuma UPGRADE.md |
standalone mode is removed |
Rename it to zone |
Kuma UPGRADE.md |
| Meshes no longer get default policies | Write the policies you relied on | Kuma UPGRADE.md |
A --to-latest v3 report checks the first two for every extracted control plane. See
Control Plane Topology.
Which target for which step
| Upgrade step | Run | Apply on |
|---|---|---|
| 2.x → a later 2.x | --to-latest v2 |
the 2.x control plane, after or before the step as the report says |
| 2.14 → 3.0, preparation | --to-latest v2 |
2.14 |
| 2.14 → 3.0, final manifests | --to-latest v3 |
3.0, after the control planes are upgraded |
v2 output stays valid on 2.x and reports 3.0 removals as advisories. v3 output removes
fields that 2.14 still requires, so it is never applied before the upgrade. See
Target versions.
Recommended sequence for 3.0
-
Upgrade to the latest 2.14 patch, two minors at a time. At each step, run
extractandmigrate --to-latest v2 --dry-runand fix what the plan reports. -
Extract every control plane into one directory: the Global control plane first, then each zone. See Extract.
kuma-migrator extract --kumactl-context global-prod --output-dir ./raw-policies --preflight kuma-migrator extract --kube-context zone-eu-west1-prod --output-dir ./raw-policies kuma-migrator extract --kube-context zone-us-east1-prod --output-dir ./raw-policies--preflightalso runs the live control plane audit (versions, CP settings, zones), and the migrate reports summarise it. On a Global it covers the settings every zone reported. Re-run it (kuma-migrator preflight) after each step below until it reportsclean. -
Dry-run both targets into separate directories. The v3 plan is the list of work the 3.0 upgrade needs.
kuma-migrator migrate -i ./raw-policies -o ./plan-v2 --dry-run kuma-migrator migrate -i ./raw-policies -o ./plan-v3 --dry-run --to-latest v3 -
Migrate to v2 and apply on 2.14. This replaces the kinds 3.0 removes with their successors while the control plane still accepts both: legacy policies become
Mesh*policies,ExternalServicebecomesMeshExternalService,OPAPolicybecomesMeshOPA, built-in gateways become Gateway API resources. Follow the Apply Checklist, skipping its control plane upgrade steps, and check traffic.kuma-migrator migrate -i ./raw-policies -o ./migrated-v2 -
Set
meshServices.mode: Exclusiveon every mesh before the Global control plane is upgraded. A 2.x zone reads a missing field asDisabledand stops servingMeshServiceoutbounds and DNS (KumaUPGRADE.md). Thev3Apply Checklist prints the command for each mesh (kubectl patch, orkumactl get | yq | kumactl apply), which changes onlymeshServices. Run it once every workload and policy usesMeshServicenames. Do not apply thev3Meshfiles here: they dropspec.mtls. See MeshService. -
Move every mesh to
MeshIdentity. This needs the previous step: on 2.14 aMeshIdentityin a mesh that is notExclusivestaysDependenciesReady=Falsewith reasonMeshServicesDisabledand never issues certificates. On 3.0Mesh.mtlsissues nothing: a mesh whose only identity source ismtlsserves plaintext andMeshTrafficPermission/MeshTLSstop applying (KumaUPGRADE.md). This is a CA cutover the manifests cannot describe; the tool reports it and does not convert it. RewriteMeshTrafficPermissionfrom[]torules[]at the same time. See mTLS and identity and Access control. In a mesh that spans zones, set up trust between zones before a second zone gets an identity: see Trust across zones. -
Migrate to v3 and review the report. If it rewrote any
MeshOPAorMeshExternalServicedata source, its Apply Checklist has a step before the Global upgrade: upgrade every control plane to 2.14.6 or later, then apply those files. 3.0 rejects the old shape and a zone below 2.14.6 cannot read the new one.kuma-migrator migrate -i ./raw-policies -o ./migrated-v3 --to-latest v3Resolve every entry under Action Items → Errors. Each
_manual/file needs a decision: rewrite it by hand, or drop it. -
Delete the removed kinds on 2.14, using Delete Before Upgrading to 3.0 in
./migrated-v3/migration-report.md. Delete an object only after its replacement from step 4 is applied and checked. -
Upgrade the Global control plane to 3.0, then each Zone control plane.
-
Apply the v3 output to the 3.0 control planes, following the Apply Checklist of
./migrated-v3/migration-report.md. Nothing under_manual/is applied. -
Restart the data planes so they pick up the 3.0
kuma-dp. -
Clean up. Once every zone runs 3.0, drop
meshServicesfrom theMeshmanifests you keep. Remove the input files and any originals still listed under Original Resources to Delete.
For 2.x-to-2.x steps, steps 2 to 4 are the whole plan: extract, dry-run with v2, migrate,
apply, then upgrade.
Use --dry-run to plan
migrate --dry-run runs every transform and every check without writing YAML. The plan
answers the planning questions directly:
| Question | Where to look in migration-plan.md |
|---|---|
| How much converts automatically | Summary: migrated vs errors |
| What needs a person | Action Items → Errors, and each warning that says BLOCKING or manual |
| What 3.0 deletes | Delete Before Upgrading to 3.0 (v3 only) |
| What workloads must change | Workload Service Address Mappings, Deprecated Annotations |
| Which files change per context | Files That Would Be Migrated, grouped by context and subfolder |
Compare the two plans to see what 3.0 adds on top of the 2.x work:
diff <(grep -o '⚠ [^|]*' ./plan-v2/migration-plan.md | sort -u) \
<(grep -o '⚠ [^|]*' ./plan-v3/migration-plan.md | sort -u)
Re-run the dry run after each fix until the error count is zero. It reads local files only, so it is safe to run as often as needed.
Read the Apply Checklist
The checklist in migration-report.md is generated from the run's output. Its steps and their
order are described in Apply. Two points matter for an upgrade plan:
- The checklist always contains the "Upgrade the Global Control Plane" and "Upgrade Zone
Control Planes" steps. In a
v2run used to prepare on the current version, skip them. - In a
v3run, the checklist orders the steps as: fix errors, setmeshServices.mode: Exclusiveon every mesh, finish theMeshIdentitycutover (when aMeshsetsspec.mtls; it needsExclusivefirst), delete the removed kinds, upgrade, apply backends then policies, apply theMeshfiles. The first four run on 2.14; theMeshfiles, which dropspec.mtls, are applied only on 3.0.
Control Plane Topology
A --to-latest v3 report opens with this section when an extracted control plane cannot run
3.0 as deployed. It is read from each context's .kuma-migrator.json (see
Extract); a context without one is not checked.
| Context | Classified as | Required change |
|---|---|---|
cpMode: standalone |
Blocking | Set KUMA_MODE=zone or controlPlane.mode: zone. 3.0 kuma-cp fails config validation on standalone and the Helm chart fails at template time. |
cpMode: global with environment: kubernetes or storeType: kubernetes, not Konnect |
Blocking | Deploy a Global kuma-cp with environment=universal on PostgreSQL (it can still run in a cluster), recreate the Global's resources on it, point every zone's controlPlane.kdsGlobalAddress at it, then retire the old one. |
cpMode: zone, not federated, extracted with kumactl |
Check | A 2.x kuma-cp started with KUMA_MODE=standalone reports zone through GET /config. Confirm the configured value is zone. |
Konnect's hosted Global control plane is never flagged. A Global control plane deployed in a
cluster with controlPlane.environment: universal and a PostgreSQL store is not flagged either.
Recreating the Global's resources uses kumactl apply, which takes Universal YAML: extract the
current Global with --kumactl-context <ctx> --output-format universal. extract skips
Secret, GlobalSecret and AccessRoleBinding, so copy those separately. Without the Mesh CA
secrets the new Global generates new CAs.
Sources: Global control plane on Kubernetes is no longer supported,
standalone mode removed,
Universal on Kubernetes using Helm.
Read Delete Before Upgrading to 3.0
This section is written by --to-latest v3 runs only. One row per source object of a kind
3.0 removes:
| Column | Meaning |
|---|---|
| Source file | The extracted file, relative to --input-dir |
| Kind, Name, Namespace / mesh | The object to delete |
| Replacement | converted (see the apply steps), or none — manual migration with the path of the _manual/ copy |
The collapsed block under the table holds the delete commands: kumactl delete for a
context extracted with kumactl from a Universal or Konnect control plane, kubectl delete
otherwise (a Kubernetes-backed control plane refuses kumactl writes). 3.0 rejects these kinds and does
not migrate stored objects, so they must be deleted on 2.14. For a row marked converted,
the replacement must come from the v2 output applied in step 4: the v3 replacement is
not valid on 2.14. The kumactl type argument is the one kumactl 2.14 registers for the kind
(traffic-permission, healthcheck, proxytemplate, zoneingress, zoneegress,
meshglobalratelimit, ...), so run the commands with a 2.14 kumactl.
Rollback
| Point | How to go back |
|---|---|
After applying v2 output on 2.x |
Delete the new-kind resources and keep the originals. The originals stay in the control plane until you delete them, and the extracted tree holds a copy. |
| After deleting removed kinds | Re-apply them from the extracted tree on 2.14. |
After the MeshIdentity cutover |
Upstream gives no rolling path back once proxies on 3.0 stop trusting legacy mesh certificates (Kuma UPGRADE.md). Plan the cutover so it is complete and verified on 2.14. |
| After upgrading to 3.0 | Store compatibility follows the two-minor rule. A 3.0 control plane drops Mesh.mtls the next time it writes a Mesh; re-apply the Mesh from the extracted tree after rolling back. |
Keep the extracted tree, both plans and both reports under version control. They record what was in the control plane before the upgrade and what changed.