CLI reference
Every command, flag and configuration file setting of kuma-migrator.
Run kuma-migrator <command> --help for the same information in the terminal. Flags are
defined in cmd/extract.go
and cmd/migrate.go.
Commands
kuma-migrator extract --kube-context <ctx> | --kumactl-context <ctx>
--output-dir <dir> [--mesh <name>]
[--output-format kubernetes|universal] [--tls-skip-verify]
kuma-migrator migrate --input-dir <dir> --output-dir <dir>
[--mesh <name>] [--to-latest v2|v3] [--dry-run]
kuma-migrator preflight [--kumactl-context <ctx> | --address <url>] [--token <token>]
[--mesh <name>] [-o <dir>] [--latest-version <2.14.x>]
[--inspect-dataplanes <n>] [--timeout <duration>]
kuma-migrator konnect token-script --region <region>
[--scope mesh|org] [--control-plane <name>]...
[--account-name <name>] [--expires-in <duration>] [-o <file>]
kuma-migrator version
kuma-migrator completion <bash|zsh|fish|powershell>
There is no plan command. migrate --dry-run replaces it, with the same flags.
extract
Reads resources from a running control plane and writes one YAML file per resource.
--kube-context and --kumactl-context are mutually exclusive, and one of them is required.
Kinds whose name contains Insight are always excluded.
| Flag | Short | Required | Default | Description |
|---|---|---|---|---|
--kube-context |
one of the two | Kubernetes context; resources are read with kubectl |
||
--kumactl-context |
one of the two | kumactl context; resources are read through the control plane API |
||
--output-dir |
-o |
yes | Directory for the extracted files. Created if missing | |
--mesh |
no | all meshes | Extract only this mesh. Global-scoped resources are always extracted | |
--output-format |
-f |
no | universal |
universal (type/name/mesh) or kubernetes (apiVersion/kind/metadata). Only affects the --kumactl-context path |
--tls-skip-verify |
-k |
no | false |
Skip TLS verification of the control plane API certificate |
--preflight |
no | false |
After extracting, run the 3.0 readiness audit against the same control plane. --kumactl-context only |
|
--latest-version |
no | from GitHub | With --preflight: latest 2.14 patch to check versions against |
|
--preflight-inspect-dataplanes |
no | 0 |
With --preflight: fetch up to N Envoy config dumps |
|
--preflight-timeout |
no | 5m |
With --preflight: overall audit timeout |
Warning: Use
--output-format kuberneteswhen the control plane behind a--kumactl-contextruns on Kubernetes. Universal output cannot be applied back to it:kumactl applyrefuses resources that Kubernetes manages as CRDs, and the store requires Universal names of the formname.namespace, which cluster-scoped legacy resources do not have.extractdetects this combination and prints a warning.
See Extract for control plane mode detection and the output layout.
migrate
Reads the extracted tree, transforms every document and writes the result. With --dry-run
it writes only migration-plan.md. Without it, it writes the migrated YAML and
migration-report.md. Both modes run the same transforms and the same deprecation scan.
| Flag | Short | Required | Default | Description |
|---|---|---|---|---|
--input-dir |
-i |
yes | Directory with the source YAML files, usually an extract output directory |
|
--output-dir |
-o |
yes | Directory for the output files and the Markdown report. Created if missing | |
--mesh |
no | all meshes | Process only mesh-<name>/ directories for this mesh. Files outside any mesh directory are always processed |
|
--to-latest |
no | v2 |
Target line: v2 (latest 2.x, 2.14) or v3 (3.0) |
|
--dry-run |
no | false |
Write migration-plan.md only, no YAML |
An invalid --to-latest value fails before any file is read:
Error: invalid --to-latest value "v4": want "v2" or "v3"
See Migrate and Target versions.
preflight
Runs the Kong Mesh 3.0 readiness audit against a running control plane and writes
v3-preflight.json and v3-preflight.html. Read-only. Exits non-zero only when the audit could
not run. See Live control plane audit.
| Flag | Short | Required | Default | Description |
|---|---|---|---|---|
--kumactl-context |
no | current kumactl context | Control plane address and token from a kumactl context, Konnect included | |
--address |
no | Control plane REST API URL instead of a kumactl context | ||
--token |
no | from the context | Bearer token. Overrides the context's token | |
--mesh |
no | all meshes | Audit only this mesh | |
--output-dir |
-o |
no | . |
Directory for the two report files |
--latest-version |
no | from GitHub | Latest 2.14 patch to check versions against, e.g. 2.14.7 |
|
--inspect-dataplanes |
no | 0 |
Fetch up to N Envoy config dumps (one request per proxy) | |
--max-resource-reads |
no | 50000 |
Cap on resources read (0 = unlimited) |
|
--timeout |
no | 5m |
Overall audit timeout | |
--tls-skip-verify |
-k |
no | false |
Skip TLS verification of the control plane API certificate |
konnect token-script
Writes the bash script a Konnect organization admin runs to create a read-only system account
and print a short-lived token for extract. It does not call Konnect.
| Flag | Short | Required | Default | Description |
|---|---|---|---|---|
--region |
yes | Konnect region: us, eu, au, me, in, sg |
||
--scope |
no | mesh |
mesh (Viewer on Mesh control planes) or org (Organization Admin (Read Only) team) |
|
--control-plane |
no | all in the region | Mesh control plane name. Repeatable. --scope mesh only |
|
--account-name |
no | kuma-migrator-readonly |
System account to create or reuse | |
--expires-in |
no | 336h |
Token lifetime, 1h to 8760h |
|
--output |
-o |
no | stdout | File to write the script to |
version and completion
kuma-migrator version and kuma-migrator --version print the build version.
kuma-migrator completion <shell> prints a shell completion script:
kuma-migrator completion zsh > "${fpath[1]}/_kuma-migrator"
Configuration file
Optional. Read from ~/.config/kuma-migrator.yaml, or from the path in
$KUMA_MIGRATOR_CONFIG. Parsed by
pkg/config/config.go.
skip:
kubernetes: [Dataplane, AccessRoleBinding, ZoneEgress, ZoneIngress, Zone, Workload, Secret, GlobalSecret]
universal: [AccessRoleBinding, Zone, Workload, Secret, GlobalSecret]
adminServer:
tlsSkipVerify: false
| Key | Effect |
|---|---|
skip.kubernetes |
Kinds never extracted or transformed in a Kubernetes environment |
skip.universal |
Kinds never extracted or transformed in a Universal environment |
skip: [Kind1, Kind2] |
Flat list, applied to both environments |
adminServer.tlsSkipVerify |
Same as --tls-skip-verify. Either one being true disables verification |
The values above are the built-in defaults. On Universal, Dataplane, ZoneIngress and
ZoneEgress are hand-written, so they are extracted and scanned. Workload is generated by
the control plane in both environments and stays skipped. AccessRole is in neither list: it
is scanned for the Kong Mesh 3.0 changes to rules[].types and when[].
migrate picks the list per context directory from the environment that extract recorded
in .kuma-migrator.json. Without that record, a document in Universal shape (type, no
kind) gets the universal list and every other document gets the kubernetes list.
Warning: An explicit list for an environment replaces the built-in default for that environment; it is not merged with it. A config file written for an older release does not pick up later changes to the defaults. Leave the key out to keep the built-in list.