Guides

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.

  1. Upgrade to the latest 2.14 patch, two minors at a time. At each step, run extract and migrate --to-latest v2 --dry-run and fix what the plan reports.

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

    --preflight also 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 reports clean.

  3. 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
    
  4. 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, ExternalService becomes MeshExternalService, OPAPolicy becomes MeshOPA, 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
    
  5. Set meshServices.mode: Exclusive on every mesh before the Global control plane is upgraded. A 2.x zone reads a missing field as Disabled and stops serving MeshService outbounds and DNS (Kuma UPGRADE.md). The v3 Apply Checklist prints the command for each mesh (kubectl patch, or kumactl get | yq | kumactl apply), which changes only meshServices. Run it once every workload and policy uses MeshService names. Do not apply the v3 Mesh files here: they drop spec.mtls. See MeshService.

  6. Move every mesh to MeshIdentity. This needs the previous step: on 2.14 a MeshIdentity in a mesh that is not Exclusive stays DependenciesReady=False with reason MeshServicesDisabled and never issues certificates. On 3.0 Mesh.mtls issues nothing: a mesh whose only identity source is mtls serves plaintext and MeshTrafficPermission/MeshTLS stop applying (Kuma UPGRADE.md). This is a CA cutover the manifests cannot describe; the tool reports it and does not convert it. Rewrite MeshTrafficPermission from[] to rules[] 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.

  7. Migrate to v3 and review the report. If it rewrote any MeshOPA or MeshExternalService data 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 v3
    

    Resolve every entry under Action Items → Errors. Each _manual/ file needs a decision: rewrite it by hand, or drop it.

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

  9. Upgrade the Global control plane to 3.0, then each Zone control plane.

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

  11. Restart the data planes so they pick up the 3.0 kuma-dp.

  12. Clean up. Once every zone runs 3.0, drop meshServices from the Mesh manifests 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 v2 run used to prepare on the current version, skip them.
  • In a v3 run, the checklist orders the steps as: fix errors, set meshServices.mode: Exclusive on every mesh, finish the MeshIdentity cutover (when a Mesh sets spec.mtls; it needs Exclusive first), delete the removed kinds, upgrade, apply backends then policies, apply the Mesh files. The first four run on 2.14; the Mesh files, which drop spec.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.