Migrates Kuma and Kong Mesh policy manifests across the API changes in the 2.x line and into 3.0 — rewrites what can be rewritten safely, and reports what cannot, with the reason.
The policy API changed substantially across 2.0–2.14, and some of the 3.0 removals are silent.
The Kuma and Kong Mesh policy API changed substantially across 2.0–2.14, and 3.0 removes a number of fields that 2.14 still accepts. Some of those removals are silent: the manifest applies cleanly and simply stops doing what it used to.
kuma-migrator automates the mechanical parts, flags the parts that need a
human, and writes a Markdown report of every change it made or would make.
Two commands, plus a manual apply step. Extract from a live control plane, migrate (preview first with --dry-run), apply. Planning a 3.0 upgrade? Add --preflight to extract to also audit the running control plane.
# 1a. Pull resources via kumactl (self-hosted OR Konnect-hosted, zonal or Global CP)
kuma-migrator extract --kumactl-context konnect-global-prod --output-dir ./raw-policies
# add --preflight to also audit that control plane for 3.0 (versions, settings, zones)
# 1b. ...or via kubectl (self-hosted, Kubernetes-backed CP)
kuma-migrator extract --kube-context zone-eu-west1-prod --output-dir ./raw-policies
# 2. Write the migrated manifests + migration-report.md
# (add --dry-run to preview first — writes migration-plan.md, no YAML)
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated
# Now read migration-report.md — it gives the exact apply order for your
# setup (Mesh resources go last: they switch on meshServices.mode: Exclusive)
# 3a. Apply them yourself if you used --kumactl-context (self-hosted or
# Konnect) — kumactl rejects a directory, so apply one file at a time
kumactl config control-planes switch --name konnect-global-prod
kumactl apply -f ./migrated/konnect-global-prod-global-ctx/mesh-default/resiliency/MeshTimeout-my-timeout.yaml
# 3b. ...or via kubectl if you extracted via --kube-context — this step
# is manual; kuma-migrator never touches your control plane's state
kubectl apply -f ./migrated/zone-eu-west1-prod-zone-ctx/mesh-default/resiliency/Applied to every legacy policy the tool touches.
targetRef, a legacy policy kind
rewritten to its Mesh* successor, and a tag/label selector expanded into a
typed reference — the same mechanism behind every conversion below.
Alongside these, every output document is scanned for deprecated and removed fields across the 2.x line and 3.0.
| Scenario | Migration |
|---|---|
| Legacy | sources/destinations/selectors policies → targetRef/to/from/rules, with the conf body rewritten to the successor's schema — except TrafficRoute (ambiguous HTTP vs TCP) and VirtualOutbound (no single successor), reported for manual migration |
| Subset | MeshSubset with service tags → Dataplane/MeshService |
| Rules | Deprecated from[] → rules[], for MeshTimeout/MeshCircuitBreaker/MeshRateLimit/MeshAccessLog/MeshTLS only (Kuma 2.10+) — MeshTrafficPermission uses a different, SPIFFE-based rules[] shape and is not auto-converted (MeshFaultInjection only under v3, when every source is kind: Mesh) |
| Mesh | Mesh CRD observability and passthrough → standalone MeshMetric/MeshTrace/MeshAccessLog/MeshPassthrough; under v3 also removes mtls and the routing fields 3.0 drops |
| ExternalService | ExternalService → MeshExternalService |
| GW | MeshGateway and MeshGatewayRoute → Gateway API. Kuma 3.0 deletes the built-in gateway API outright, so under v3 MeshGatewayInstance is reported rather than converted, and the source objects must be deleted before upgrading. MeshHTTPRoute/MeshTCPRoute are current policies on both lines and pass through unchanged |
| OPAPolicy | Kong Mesh OPAPolicy → MeshOPA |
Why MTP's from[] is never auto-converted:
MeshTrafficPermission and access control.
Full list: policy reference, one page per resource kind.
--to-latest v2|v3One output cannot serve both lines.
migrate (including its --dry-run mode) takes --to-latest v2
(default, latest 2.x) or v3 (Kuma / Kong Mesh 3.0, checked against the released
3.0.0 upgrade notes). 3.0 removes fields 2.14 still requires, and some 3.0 replacements
(MeshOpenTelemetryBackend, SecureDataSource) do not exist before
2.14.
v2 keeps the output applicable to a 2.x control plane and
reports 3.0 removals as forward-looking advisories.
v3 rewrites what it safely can and flags the rest. What 3.0
cannot accept goes to a separate _manual/ subtree that no apply step uses, and
the report lists the objects to delete before the upgrade. A v3 report carries a banner
warning that the output must not be applied to a 2.x CP.
Every release archive carries a build provenance attestation.
You do not have to trust that a downloaded archive matches this repository — you can check. Each release binds its archives to the exact commit and GitHub Actions run that built them, cryptographically, via GitHub build provenance attestation.
VERSION=$(gh release view --repo Kong/kuma-migrator --json tagName --jq '.tagName' | tr -d 'v')
curl -LO "https://github.com/Kong/kuma-migrator/releases/latest/download/kuma-migrator_${VERSION}_linux_amd64.tar.gz"
gh attestation verify "kuma-migrator_${VERSION}_linux_amd64.tar.gz" --repo Kong/kuma-migrator
The same digests appear in the release's checksums.txt, in the attestation,
and in the Homebrew cask's sha256 fields — nothing is rebuilt in between.
brew install --cask bcollard/kuma-migrator/kuma-migrator
Download the binary for your platform from the
GitHub Releases page —
Linux and macOS (amd64/arm64), Windows (amd64).
git clone https://github.com/Kong/kuma-migrator.git && cd kuma-migrator
make build
# binary at ./dist/kuma-migratorFull options: installation guide.
Everything above is the short version. Each page below goes deeper on one part of it.
| Page | What it covers |
|---|---|
| Installation | Homebrew, binaries, from source |
| CLI reference | Every command, flag, and the config file |
| Extracting from a control plane | CP-mode rules, output layout, Konnect, Universal vs Kubernetes format |
| Konnect read-only access | A short-lived read-only token for Konnect, from kuma-migrator konnect token-script |
| Live control plane audit | The 3.0 readiness audit of a running control plane: kuma-migrator preflight or extract --preflight |
| Plan and migrate | Dry run, output layout, Gateway API placement |
| Choosing a target version | --to-latest and the checks that change with it |
| Applying the migrated manifests | Apply order, and cleaning up changed kinds |
| Topics | Meshes, mTLS and identity, MeshService, multizone, gateways, observability: one concept per page |
| Policy reference | Every resource kind: what v2 and v3 do with it, and why |
| Access control | MeshTrafficPermission from[] vs rules[], and why it is not mechanical |
| Gateways and routing | MeshHTTPRoute on 3.0: the 404 change, and the targetRef matrix for every policy |
| Transformation examples | Before-and-after YAML per scenario |
| Console output and reports | What you see, and what the report contains |
| Notes and caveats | Behaviour worth knowing before relying on the output |
All guides, topics and the policy reference: documentation home.
23 releases since April 2026. Full history: Releases · compare view.
kuma-migrator preflight audits a running control plane (versions, CP settings, zones, stored resources, optionally Envoy config) and writes v3-preflight.json and .html; extract --kumactl-context … --preflight runs it after extracting, and the migrate report adds a Live Control Plane Audit section. Konnect contexts work with the read-only token. See Live control plane audit.kuma-migrator konnect token-script writes the script a Konnect org admin runs to give extract a short-lived read-only token, without sharing an admin token (Konnect read-only access). New 3.0 checks, cross-checked with the Mesh team's readiness tool: proxyTypes in a targetRef (and the default mesh-gateways-timeout-all policy, which 3.0 widens to every sidecar), kafka protocol, named directAccessServices, legacy Retry fields in MeshRetry. Fixes: Mesh.metrics → MeshMetric keeps the full metric set and the client certificate check; converted MeshService refs are pinned to the proxy's zone; rewritten MeshOPA/MeshExternalService files are applied on 2.14.6+ before the Global upgrade; the MeshIdentity advice covers insecureAllowSelfSigned and trust across zones._manual/ file is rejected by 3.0 for the stated reason, and a new e2e CI workflow keeps it that way. Fixes found that way: extract no longer drops resources without an origin label on zone CPs, extracts Universal HealthCheck, keeps hand-written MeshServices and strips server-set fields; converted policies keep their mesh-wide scope (system namespace) and Universal format; legacy values the new schemas reject (ProxyTemplate operations, header names, bandwidth units, SourceIP) are normalised; the Apply Checklist uses kubectl replace for rewritten objects, sets Exclusive before the MeshIdentity step and only prints commands that exist. New 3.0 checks: Mesh.constraints, route backendRef ports, control-plane topology.--to-latest v3, audited against the released 3.0.0/3.0.1 upgrade notes: Mesh.mtls removal (MeshIdentity cutover first), labels-only selection, control-plane-owned labels, Dataplane, MeshService, MeshPassthrough, zone proxy, Gateway API and Kong Mesh RBAC changes. Documents 3.0 rejects go to a _manual/ subtree, and the report gains a "Delete Before Upgrading to 3.0" section. Breaking: Mesh logging/tracing no longer produce mesh-wide companions; companions default to kuma-system unless the input shows Kong Mesh (override with systemNamespace:); v2 service references use Dataplane labels instead of a name. New documentation site with guides, topics and a per-policy v2/v3 reference.MeshHTTPRoute/MeshTCPRoute are no longer converted to Gateway API. Both are current policies on 2.x and 3.0 — Kuma compiles HTTPRoute/GRPCRoute into a MeshHTTPRoute — and Kuma has never reconciled Gateway API TCPRoute at all, so that output was dead on every version. They now pass through unchanged, and the 3.0 404 catch-all advisory fires on the MeshHTTPRoute itself.--to-latest v3 delegated-gateway guidance: Kuma 3.0 removes the kuma.io/gateway marking rather than renaming it, so the tool now points at traffic.kuma.io/exclude-inbound-ports and kuma.io/ignore. Top-level targetRef checks apply 3.0's uniform Mesh/Dataplane-only rule to every policy, and converted MeshGateway/MeshGatewayRoute objects now carry a delete-before-upgrading advisory.plan command — use migrate --dry-run instead, same flags and output. Also redesigned the pipeline diagram to mark apply as a manual step, not a command.HostnameGenerator being misclassified as "Skipped".gh attestation verify.--to-latest v3 gaps found auditing upstream kuma/kong-mesh: Dataplane BUILTIN gateway type, MeshOPA targetRef/DataSource fixes, MeshLoadBalancingStrategy crossZone, MeshHTTPRoute catch-all.Gateway.spec.gatewayClassName to resolve a real GatewayClass instead of a dead controllerName string; stopped emitting a dead built-in-gateway pair under v3.conf bodies are converted to the successor's schema instead of copied verbatim.--to-latest v2|v3 targeting, closed 2.13/2.14 deprecation gaps, fixed OPAPolicy handling and an extract data-loss bug.MeshIdentity/MeshTrust mtls advisory.migrate/plan output shows mesh name and file paths.MeshService names.--output-format flag, context-first output directory layout, per-environment skip lists.-k/--tls-skip-verify; stopped trusting readOnly from /_resources.