Topics
Migration planning by area of the mesh — what changed upstream, what kuma-migrator does on each target, and the manual steps left to you.
A topic page covers one area of a mesh — identity, gateways, multizone, access control — across
every resource kind that touches it. Use it to plan the migration of that area: what changed
upstream between 2.x, 2.14 and 3.0, what kuma-migrator rewrites with --to-latest v2 and
--to-latest v3, what it cannot rewrite and why, and the manual steps in the order to run them.
The policy pages cover the same ground from the other direction: one page per resource kind, with its status on each target and the files that handle it. A topic page links to the policy pages of every kind it discusses.
How to read a topic page
| Section | Content |
|---|---|
| What changed upstream | The upstream changes with the version that introduced them, linked to the Kuma UPGRADE.md, the Kong Mesh upgrade notes or the docs page they come from |
| What kuma-migrator does | A v2 / v3 comparison table |
| What it cannot do | The information the fix needs that a manifest does not carry |
| Manual steps | The remaining work, in the order to run it |
| Example | Input and output from a real migrate run. Output is never written by hand |
Every example was produced by running kuma-migrator migrate --input-dir in --output-dir out --to-latest v2|v3 on the input shown. Warnings quoted on these pages are shortened; the full
text is in migration-report.md.
Pages
| Topic | Covers |
|---|---|
| Meshes | The Mesh resource: observability, passthrough, routing and meshServices fields |
| mTLS and workload identity | Mesh.mtls → MeshIdentity + MeshTrust, PERMISSIVE → MeshTLS |
| External PKI | Kong Mesh Vault, ACM Private CA and cert-manager backends → MeshIdentity Extension provider |
| MeshService | kuma.io/service tags → MeshService, meshServices.mode, hostnames, names |
| Multizone | Control plane modes, origin filtering, zone proxies, cross-zone load balancing |
| Gateways, Gateway API and GAMMA | Built-in gateway removal, MeshGateway* → Gateway API, MeshHTTPRoute on 3.0 |
| External services | ExternalService → MeshExternalService, TLS data sources, passthrough |
| Access control | MeshTrafficPermission from[] vs rules[], MeshOPA, Kong Mesh RBAC |
| Observability | Metrics, tracing and access logs; OpenTelemetry backends |
| Policy targeting | targetRef kinds per position and target, policy roles, control-plane-owned labels |
| Dataplanes | Universal Dataplane fields and Pod annotations removed in 3.0 |
| Legacy policies | The 12 source/destination policies and their Mesh* successors |
Before you start
- Pick the target first. Choosing a target version explains why
the
v2andv3outputs differ and must not be mixed. - Kong Mesh supports upgrading at most two minor versions at a time, so a fleet on 2.8 goes
2.8 → 2.10 → 2.12 → 2.14 before 3.0. Most 3.0 preparation has to be applied on 2.14, because
the replacements (
MeshIdentityextensions,MeshOpenTelemetryBackend, theSecureDataSourceshape) do not exist earlier. - Extract from every control plane that holds resources, not only the Global one. See Multizone and Extract.
Meshes
Every field of the Mesh resource that changed between 2.x and 3.0, and what kuma-migrator does with each one.
mTLS and workload identity
Moving a mesh from Mesh.mtls to MeshIdentity and MeshTrust before Kuma 3.0, and why kuma-migrator reports it instead of rewriting it.
External PKI
Moving Kong Mesh Vault, ACM Private CA and cert-manager mTLS backends to the MeshIdentity Extension provider before Kong Mesh 3.0.
MeshService
Moving policies, routes and workload addresses from kuma.io/service tags to MeshService, and setting meshServices.mode before Kuma 3.0.
Multizone
Control plane modes, which control plane to extract from, zone proxies, MeshMultiZoneService and cross-zone load balancing across 2.x and 3.0.
Gateways, Gateway API and GAMMA
The built-in gateway removal in Kuma 3.0, MeshGateway* to Gateway API, delegated gateways, and why MeshHTTPRoute and MeshTCPRoute stay.
External services
ExternalService to MeshExternalService, the SecureDataSource TLS shape, MeshPassthrough, and what Kuma 3.0 requires for traffic leaving the mesh.
Access control
MeshTrafficPermission from[] versus SPIFFE rules[], MeshOPA, and the Kong Mesh RBAC changes in 3.0 — what kuma-migrator converts and what stays manual.
Observability
Metrics, tracing and access logs from Mesh fields and legacy policies to MeshMetric, MeshTrace, MeshAccessLog and MeshOpenTelemetryBackend.
Policy targeting
Which targetRef kinds each policy accepts at each position on 2.14 and 3.0, labels-only selection, policy roles, and control-plane-owned labels.
Dataplanes
Universal Dataplane fields and Kubernetes Pod annotations that change or disappear between 2.x and 3.0, and what kuma-migrator rewrites.
Legacy policies
The twelve source/destination policies Kuma 3.0 removes, how kuma-migrator maps their selectors and conf to the Mesh* successors, and the two it leaves to you.