Documentation
How to use kuma-migrator to move Kuma and Kong Mesh manifests across the 2.x API changes and into 3.0.
kuma-migrator reads the resources of a running Kuma or Kong Mesh control plane, rewrites
them for the latest 2.x line or for 3.0, and writes a report of every change, every warning
and every step left to you. It never writes to a control plane: you review the output and
apply it yourself.
Quick start
brew install --cask bcollard/kuma-migrator/kuma-migrator
kuma-migrator extract --kube-context prod-eks --output-dir ./raw-policies
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated --dry-run
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated
less ./migrated/migration-report.md # follow its Apply Checklist
Add --to-latest v3 to migrate to target Kuma / Kong Mesh 3.0. Start with
Getting started for your setup.
How the documentation is organised
| Section | Organised by | Use it to |
|---|---|---|
| Guides | Task | Install the tool, run extract and migrate, read the report, plan an upgrade, apply the output |
| Topics | Area of the mesh | Plan one area (identity, gateways, multizone, access control, observability, …) across every kind that touches it |
| Policies | Resource kind | Look up what the tool does with one kind on each target, the kinds it emits, and the upstream changes behind it |
A typical path: Upgrade plans for the order of work, the topics for the areas your plan flags, and the policy pages for the kinds in your report.
Guides
Install kuma-migrator, run it against your control planes, plan an upgrade, and apply the result.
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.
Policy reference
One page per Kuma and Kong Mesh resource kind — what kuma-migrator does with it under --to-latest v2 and v3, and the upstream changes behind it.