Migrate
Preview the migration with --dry-run, write the migrated manifests, and the output layout they land in.
migrate reads a directory of Kuma manifests, usually the output of extract,
transforms every document and writes the result plus a Markdown report. It never contacts a
control plane.
--dry-run runs the same transforms and the same deprecation scan. It changes two things:
no YAML is written, and the report is migration-plan.md instead of migration-report.md.
Dry run
Point --input-dir at the whole extracted tree. Filter to one mesh with --mesh if needed.
# All meshes
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated --dry-run
# One mesh
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated --mesh default --dry-run
# Target 3.0 instead of the latest 2.x
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated --to-latest v3 --dry-run
The console lists every file with its scenario, where it came from and where it would be
written, followed by warnings and errors. migration-plan.md in the output directory holds the
same information. See Output and reports.
Write the output
Run the same command without --dry-run:
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated --mesh default
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated --to-latest v3
This writes the migrated YAML and migration-report.md. The input directory is never
modified. Use a separate output directory per target, for example ./migrated-v2 and
./migrated-v3: the two targets produce different files, and a run does not delete files left
by a previous run in the same directory.
See Target versions for what --to-latest changes, and
Apply for the order to apply the output in.
Mesh filter
--mesh <name> keeps files under mesh-<name>/ and drops files under other mesh-*/
directories. Files that are not under a mesh directory (global-scoped-resources/, a flat
input tree) are always processed.
Input layout
migrate recognises the context and mesh from the path of each file:
Path below --input-dir |
Context directory | Mesh |
|---|---|---|
<sub>/file.yaml |
none | none |
<dir>/<sub>/file.yaml |
<dir> |
none |
<ctx>/global-scoped-resources/<sub>/file.yaml |
<ctx> |
none |
<ctx>/mesh-<mesh>/<sub>/file.yaml |
<ctx> |
<mesh> |
<sub> is one of the kind subfolders (resiliency, routing, zero-trust, observability,
mesh, other). A hand-built input tree works as long as it follows one of these shapes.
Every file ending in .yaml or .yml is read; a file can hold several documents separated by
---.
Output layout
The output mirrors the input layout. Each document is written to the kind subfolder of its
output kind, named <Kind>-<name>.yaml, or <Kind>-<namespace>-<name>.yaml when it has a
namespace.
migrated/
konnect-global-prod-global-ctx/
mesh-default/
backends/ ← MeshOpenTelemetryBackend, applied first
resiliency/
MeshTimeout-my-timeout.yaml
routing/
zero-trust/
observability/
mesh/
Mesh-default.yaml
other/
global-scoped-resources/
routing/
Gateway-gateways-edge.yaml
HTTPRoute-gateways-edge.yaml
other/
ReferenceGrant-apps-gateways-edge.yaml
_manual/ ← never applied
mesh-default/routing/TrafficRoute-route-all.yaml
zone-eu-west1-prod-zone-ctx/
mesh-default/
resiliency/
migration-report.md
| Output | Location |
|---|---|
| Kuma resources from a mesh directory | <ctx>/mesh-<mesh>/<sub>/ |
| Kuma resources with no mesh directory | <ctx>/global-scoped-resources/<sub>/ |
Gateway API output (Gateway, HTTPRoute, TCPRoute, GatewayClass, ReferenceGrant) |
<ctx>/global-scoped-resources/<sub>/, even when the source came from a mesh directory. ReferenceGrant has no kind subfolder of its own and lands in other/ |
Originals whose conversion failed and converted output the target rejects as written (either target), and kinds 3.0 removes (--to-latest v3) |
<ctx>/_manual/<same relative path> |
| Flat input (no context directory) | <sub>/ |
Gateway API resources are Kubernetes-native objects applied to the clusters that run the
gateway, not Kuma resources stored by the Global control plane. They are grouped under
global-scoped-resources/ so that the per-mesh directories only hold Kuma resources. A
converted gateway from a Zone control plane lands in <zone-ctx>/global-scoped-resources/routing/.
See Gateways.
MeshHTTPRoute and MeshTCPRoute are not converted. They pass through to
<ctx>/mesh-<mesh>/routing/ unchanged. See MeshHTTPRoute.
One input document can produce several output documents:
| Input | Extra output |
|---|---|
| Legacy policy with several specific sources | one policy per source, named <name>-0, <name>-1, … |
Mesh* policy with both from[] and to[] |
the to[] half as <name>-outbound |
Mesh with embedded observability or passthrough |
MeshMetric, MeshTrace, MeshAccessLog, MeshPassthrough |
Mesh under --to-latest v3 |
MeshTLS (permissive backend), MeshPassthrough |
Inline OpenTelemetry endpoint under --to-latest v3 |
MeshOpenTelemetryBackend in backends/, which the Apply Checklist applies before the policies that select it |
MeshGatewayRoute with a cross-namespace backend |
ReferenceGrant |
MeshGatewayInstance under --to-latest v2 |
GatewayClass + MeshGatewayConfig |
Errored documents are copied unchanged to _manual/, which no apply step uses, on both
targets. Under --to-latest v2 applying the copy back to the 2.x control plane it came from
would change nothing, but listing it among the apply steps read as if it had been migrated.
When a transform knowingly produces output the target rejects, that output (not the original)
goes to _manual/. The report lists every _manual/ file under Kept Under _manual/ with
its reason, and the errored or rejected ones again under Action Items → Errors.
migrate drops metadata.resourceVersion and metadata.uid from every written document.
extract copies them from kubectl get -o yaml, and both make a later kubectl replace or
kubectl apply fail with a conflict once the live object has changed.
Scenarios
Each document is classified into one scenario, which decides the transform:
| Scenario | Trigger | Output |
|---|---|---|
| Legacy | sources/destinations/selectors, or one of the legacy kinds |
Mesh* policy with targetRef/to/from/rules/default |
| Subset | MeshSubset with service tags, or MeshService with a Kuma-generated _svc_ name |
Dataplane/MeshService references |
| Rules | MeshTimeout, MeshCircuitBreaker, MeshRateLimit, MeshAccessLog, MeshTLS with from[] |
rules[] |
| Mesh | Mesh with embedded observability or passthrough |
standalone policies |
| ExternalService | ExternalService |
MeshExternalService |
| Gateway | MeshGateway, MeshGatewayInstance, MeshGatewayRoute |
Gateway API |
| OPAPolicy | Kong Mesh OPAPolicy |
MeshOPA |
| Passthrough | anything already current | unchanged, still scanned |
The per-kind behaviour on each target is on the policy pages. How the pipeline is put together is in Architecture.