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.