Guides
Install kuma-migrator, run it against your control planes, plan an upgrade, and apply the result.
The guides cover the tool itself: how to install it, how to run each command, what it writes, and how to use its output to plan and carry out an upgrade. For what happens to a specific resource kind, see the policy pages; for one area of the mesh across kinds, see the topics.
Getting started
| Guide | What it covers |
|---|---|
| Installation | Homebrew, release archives, building from source, verifying a release |
| Getting started | The three steps of a migration, illustrated, then end-to-end runs for a single Kubernetes zone, multizone, self-hosted Kong Mesh, Konnect and Universal |
| Upgrade plans | Supported upgrade paths, which target to use when, the sequence for 3.0, rollback |
Running the tool
| Guide | What it covers |
|---|---|
| CLI reference | Every command, flag and configuration file setting |
| Extract | Reading a control plane: connection modes, control plane modes, origin filtering, layout |
| Konnect read-only access | A short-lived read-only token for a Konnect-hosted Global, created by an org admin with a generated script |
| Live control plane audit | preflight and extract --preflight: the 3.0 readiness audit of a running control plane |
| Migrate | --dry-run, the real run, input and output layout, scenarios |
| Target versions | --to-latest v2 and v3: what each rewrites, warns about or refuses |
| Apply | The Apply Checklist, apply order, removing originals, the _manual/ subtree |
| Output and reports | Console output and the sections of the Markdown report |
Reference
| Guide | What it covers |
|---|---|
| Transformation examples | Before-and-after YAML per scenario, on both targets |
| Architecture | How the pipeline is built, with links to the source |
| Notes and caveats | Behaviour to know before relying on the output |
Installation
Install kuma-migrator with Homebrew, from a release archive, or from source, and verify a release archive.
Getting started
A migration in three steps, extract, migrate and apply, followed by a walkthrough for each kind of deployment.
Upgrade plans
Plan a Kuma or Kong Mesh upgrade with kuma-migrator, from the next 2.x minor to 3.0, and read the report sections that drive it.
CLI reference
Every command, flag and configuration file setting of kuma-migrator.
Extract
Pull resources out of a running Kuma or Kong Mesh control plane, and the control plane mode rules that decide what is kept.
Konnect read-only access
Give kuma-migrator read access to a Konnect-hosted Mesh Global control plane with a short-lived system account token, without sharing an admin token.
Live control plane audit
Audit a running 2.x control plane for Kong Mesh 3.0 readiness with kuma-migrator preflight or extract --preflight, and read the result in the migrate report.
Migrate
Preview the migration with --dry-run, write the migrated manifests, and the output layout they land in.
Target versions
Why the 2.x and 3.0 lines need different output, and what --to-latest v3 rewrites, warns about or refuses.
Apply
The order to apply the migrated manifests in, why the order matters, and how to remove the originals afterwards.
Output and reports
What migrate prints while it runs, and what the Markdown report contains.
Transformation examples
Before-and-after YAML for each migration scenario, as produced by the current release.
Architecture
How kuma-migrator is built, from reading the control plane to writing the report.
Notes and caveats
Behaviour worth knowing before you rely on the output.