Notes and caveats
Behaviour worth knowing before you rely on the output.
What is rewritten
- Targeting and structure change; configuration values do not. Legacy
confbodies are converted field by field to the successor'sdefaultschema, and every input field that has no equivalent is reported. In policies that are alreadyMesh*kinds, fields insidedefaultare only changed to fix a known deprecated field. See Legacy policies. - Unrelated fields are kept. Transforms work on the parsed document and keep top-level
fields they do not own, including Universal
type,name,meshandlabels. TrafficRouteandVirtualOutboundare not converted on either target.TrafficRoutemaps to MeshHTTPRoute or MeshTCPRoute depending on the protocol, which the manifest does not say.VirtualOutboundhas no single successor. Both are reported as errors.- Several sources become several policies.
spec.targetReftakes a single reference, so a legacy policy with several specific sources is split into<name>-0,<name>-1, …. from[]andto[]in one policy become two. Kuma 2.10+ does not acceptrules[]andto[]together, so theto[]half is written as<name>-outbound. Apply both.rules[]conversion ignores whetherspec.targetRefis set. Any affected kind withfrom[]is converted.
Service names
kuma.io/servicevalues in the Kubernetes encoding (backend_demo_svc_3001) are decoded into name, namespace and port. Universal service names are free-form and used as they are.- A top-level
MeshSubsetwith a service tag becomeskind: Dataplane. Where the reference needs labels,app: <service>is used as a best guess for the Pod label and a warning is printed. Check it against your Pods. - A partially migrated policy that already says
kind: MeshServicebut still uses the Kuma-generated name (echo_demo_svc_8000) is decoded the same way.
Gateway API output
- A bare
*hostname on aMeshGatewaylistener is not valid Gateway API. The listener is written without a hostname, which accepts any hostname, and a warning is printed. - Backend references decode the
kuma.io/servicevalue into Service name, namespace and port. A missing or invalid port is reported. A backend in another namespace than the route gets a generatedReferenceGrant; when the route has no namespace, a warning is printed instead. gatewayClassNameis resolved from theMeshGatewayInstancethat shares the gateway'skuma.io/servicetag. When none is found, it is set toREPLACE-WITH-YOUR-GATEWAYCLASSand a warning is printed. See Gateways.
Environments and formats
- Both YAML shapes are read. Kubernetes format (
apiVersion,kind,metadata) and Universal format (type, top-levelname/mesh) are supported byextractandmigrate. - The output keeps the input format. Universal input gives Universal output (
type,name,mesh, top-levellabels, body underspec), including every generated companion (MeshCircuitBreakerfrom aHealthCheck,MeshOpenTelemetryBackend,MeshTLS, ...). Kubernetes input gives Kubernetes resources. Gateway API output (Gateway,HTTPRoute, ...) is always Kubernetes: it exists only there. - Companion policies go in the system namespace. On Kubernetes, policies generated from a
Mesh(MeshMetric,MeshPassthrough,MeshTLS,MeshOpenTelemetryBackend) are placed in the control-plane namespace:systemNamespacefrom the config file, else the namespace inferred from the input, elsekuma-system. See Meshes. - The skip list depends on the environment. On Kubernetes,
Dataplane,ZoneIngress,ZoneEgressandWorkloadare skipped: the control plane generates them. On Universal the first three are hand-written and are scanned.migrateuses theenvironmentthatextractrecorded in.kuma-migrator.json. Askiplist in the configuration file replaces the default for its environment. - Universal
Dataplanechecks. The scan reportstransparentProxying.redirectPortInboundV6(removed in 2.9) andtransparentProxying.reachableServices(names must beMeshServicedisplay names once the mesh runsmeshServices.mode: Exclusive). Under--to-latest v3it also handles everything 3.0 removes fromDataplane. See Dataplanes.
Operations
- Upgrade in steps of at most two minor versions, for Kuma and Kong Mesh alike, for example 2.10 → 2.12 → 2.14 → 3.0. As of 2026-10-30 the latest releases are Kuma 3.0.1 and Kong Mesh 3.0.1, with 2.14.7 and 2.13.12 (LTS) patch releases. See Upgrade plans.
- Self-signed control plane certificates. Use
-k/--tls-skip-verify, oradminServer.tlsSkipVerify: truein~/.config/kuma-migrator.yaml. - Nothing is applied for you.
migratewrites files; applying them is a manual step that follows the report's Apply Checklist. See Apply.