Guides

Output and reports

What migrate prints while it runs, and what the Markdown report contains.

Console output

Each input file gets one line: a status icon, a scenario label, the mesh (omitted for global-scoped files) and the file name. Two faint lines below show the input path (←) and the first output path (→), relative to --input-dir and --output-dir. Warnings follow as ⚠, errors as ✗.

Output of migrate --dry-run on a Global and a Zone context (warnings shortened):

  kuma-migrator  migrate --dry-run

  ✓  MESH              default  default.yaml
       ←  kind-global-global-ctx/mesh-default/mesh/default.yaml
       →  kind-global-global-ctx/mesh-default/mesh/Mesh-default.yaml
       ⚠  Mesh.spec.meshServices.mode set to Exclusive — required for MeshService-based policies to take effect (Kuma 2.9+). …
       ⚠  Mesh "default": spec.mtls is the legacy mTLS/identity model and is removed in Kuma 3.0. …
  ✓  LEGACY            default  timeout-default.yaml
       ←  kind-global-global-ctx/mesh-default/resiliency/timeout-default.yaml
       →  kind-global-global-ctx/mesh-default/resiliency/MeshTimeout-backend-timeout.yaml
  ⚠  PARTIAL ERROR     default  route.yaml
       ←  kind-global-global-ctx/mesh-default/routing/route.yaml
       →  kind-global-global-ctx/_manual/mesh-default/routing/TrafficRoute-route-all-default.yaml
       ✗  TrafficRoute requires manual migration to MeshHTTPRoute or MeshTCPRoute
  ✓  SUBSET            default  meshretry.yaml
       ←  kind-zone-eu-zone-ctx/mesh-default/resiliency/meshretry.yaml
       →  kind-zone-eu-zone-ctx/mesh-default/resiliency/MeshRetry-demo-backend-retry.yaml
  ✓  RULES             default  meshtimeout.yaml
       ←  kind-zone-eu-zone-ctx/mesh-default/resiliency/meshtimeout.yaml
       →  kind-zone-eu-zone-ctx/mesh-default/resiliency/MeshTimeout-demo-backend-inbound.yaml
       ⚠  MeshTimeout "backend-inbound": from[] migrated to rules[] (Kuma 2.10+). …

  ────────────────────────────────────────────────────────────
  5 file(s) processed  ·  4 migrated  ·  0 already migrated  ·  0 skipped  ·  1 error(s)


Report written to: migrated/migration-plan.md
Label Meaning
LEGACY, SUBSET, RULES, MESH, EXTERNAL SERVICE, GATEWAY, OPA Migrated, by scenario
REWRITTEN Already uses the current API, but the output differs from the input: a fix for the target changed it (for example --to-latest v3 turning name/namespace refs into labels, stripping control-plane-owned labels, or replacing an inline OpenTelemetry endpoint with a generated MeshOpenTelemetryBackend). Counted as migrated; the report's Scenario column says Passthrough, rewritten for the target
ALREADY MIGRATED Passed through unchanged; already uses the current API
SCANNED Not a policy (Dataplane, Deployment, ...), but the deprecation scan rewrote it or warned about it. Written to the output tree. The detail says rewritten by the deprecation scan or copied unchanged, see warnings
MANUAL Every document is a kind the target removes, with no conversion (MeshGatewayConfig, MeshGlobalRateLimit, Universal ZoneIngress/ZoneEgress under v3). Written to _manual/ only
SKIP Not a policy and nothing to change: not a Kuma policy; copied unchanged, or on the skip list; not written
ERROR The file could not be read or written
PARTIAL ERROR At least one document in the file could not be converted, or its output is rejected by the target; the rest were converted. The original (or the rejected output) is written to _manual/

The deprecation scan runs on every document, whatever its label. A Kubernetes Deployment with a deprecated kuma.io/* annotation is labelled SCANNED rather than SKIP, and a Universal Dataplane whose inbound tags --to-latest v3 rewrites is labelled SCANNED with rewritten by the deprecation scan. A HostnameGenerator passes through (ALREADY MIGRATED), but its spec.template is still checked against the 2.14 validation.

The summary line adds N scanned and N manual when those counts are not zero.

Report sections

migrate --dry-run writes migration-plan.md; migrate writes migration-report.md. Both are written to --output-dir by pkg/migrator/report.go.

Section Content
Header Input and output directories, the target (v2 or v3). Under v3, a banner that the output must not be applied to a 2.x control plane. Under --dry-run, a banner that no files were written
Live Control Plane Audit Present when a context directory holds a v3-preflight.json (from extract --preflight or preflight -o <context dir>). Per context: status, control plane, blocker table with examples, coverage gaps, path to the HTML report. See Live control plane audit
Summary Files processed, migrated, already migrated, scanned, kept under _manual/ (when any), skipped, errors
Files That Would Be Migrated (--dry-run) / Migrated Files One table per <context>/<subfolder>/, for example kind-global-global-ctx/resiliency/, with the warnings of each file. REWRITTEN files are listed here too. Errored files are grouped separately
Already Migrated Files passed through unchanged, with their warnings
Scanned Non-Policy Resources Non-policy files the deprecation scan rewrote or flagged, with their warnings
Kept Under _manual/ Every file written to _manual/, one row each: source file, kind, name, _manual/ path, and the reason (kind removed in 3.0, not converted with the conversion error, or rejected by the target with the rejection reason)
Skipped Non-policy files with nothing to change, and whether they were copied or skip-listed
Action Items Errors, workload service address mappings, deprecated annotations. Present only when one of them is non-empty. A document the target rejects as written is listed under Errors with the _manual/ path of its converted output
Apply Checklist Ordered steps with the kubectl or kumactl commands for each context: kubectl replace for files that rewrite an input object, kubectl apply for the rest. A three-step version under --dry-run. See Apply
Original Resources to Delete Resources whose kind changed, with delete commands in a collapsible block. Under v3, kinds 3.0 removes are listed in the next section instead
Delete Before Upgrading to 3.0 v3 only. See below

Delete Before Upgrading to 3.0

Under --to-latest v3 this section lists every source object of a kind 3.0 removes: the legacy policies, ExternalService, OPAPolicy, MeshGlobalRateLimit, MeshGateway, MeshGatewayRoute, MeshGatewayInstance, MeshGatewayConfig, and ZoneIngress/ZoneEgress. For each it shows whether it was converted, where its _manual/ copy is if it was not, and the delete command. The command uses kumactl for contexts extracted with kumactl from a Universal or Konnect control plane, and kubectl otherwise, including kumactl extracts of a Kubernetes-backed control plane (kumactl cannot delete there) and the Kubernetes-only kinds MeshGatewayInstance and MeshGatewayConfig.

| Source file | Kind | Name | Namespace / mesh | Replacement |
|---|---|---|---|---|
| `kind-global-global-ctx/mesh-default/resiliency/timeout-default.yaml` | `Timeout` | `backend-timeout` | mesh `default` | converted (see the apply steps) |
| `kind-global-global-ctx/mesh-default/routing/route.yaml` | `TrafficRoute` | `route-all-default` | mesh `default` | none — manual migration, copy at `kind-global-global-ctx/_manual/mesh-default/routing/TrafficRoute-route-all-default.yaml` |

The Apply Checklist gets a matching step before the Global control plane upgrade. See Upgrade plans for where it fits.