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 v2 and v3 outputs 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 (MeshIdentity extensions, MeshOpenTelemetryBackend, the SecureDataSource shape) 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.