Guides

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 reads manifests. Some 3.0 blockers are not in any manifest: the control plane and zone versions, control plane settings, zones that are offline, the default policies the control plane created, and features in the Envoy configuration of running proxies. The readiness audit reads those from the running control plane.

The audit is the engine of kong-mesh-v3-preflight, written by the Kong Mesh engineering team (Kong/kong-mesh-v3-readiness, Apache 2.0). kuma-migrator imports it as a Go library, so it needs no separate install.

migrate --to-latest v3 Readiness audit
Reads Extracted YAML files The control plane REST API
Writes Rewritten manifests, report, Apply Checklist v3-preflight.json, v3-preflight.html
Covers Fields and kinds to rewrite or remove Versions, CP settings, zones, stored resources, Envoy config
Changes anything Output files only Nothing, read-only

Run both before an upgrade. Several checks overlap (a Mesh without meshServices.mode: Exclusive, from[] on MeshTimeout); the migrate output fixes those, the audit confirms what is still on the control plane.

Audit while extracting

Add --preflight to a --kumactl-context extraction. The audit runs after the files are written, against the same control plane and token:

kuma-migrator extract --kumactl-context prod-global -o ./raw-policies --preflight
kuma-migrator migrate --input-dir ./raw-policies --output-dir ./migrated --to-latest v3

The report files land in the context directory, next to .kuma-migrator.json:

raw-policies/
  prod-global-global-ctx/
    .kuma-migrator.json
    v3-preflight.json
    v3-preflight.html
    mesh-default/...

A failed audit is printed as a warning and does not fail the extraction. migrate reads only .yaml files, so the report files do not affect the migration.

--preflight needs the control plane API, so it is refused with --kube-context. Port-forward the control plane and run preflight --address instead (below).

Audit on its own

# the current kumactl context
kuma-migrator preflight -o ./audit

# a named context, Konnect included
kuma-migrator preflight --kumactl-context prod-global -o ./audit

# an address, e.g. a port-forwarded Kubernetes control plane
kubectl port-forward -n kong-mesh-system svc/kong-mesh-control-plane 5681 &
kuma-migrator preflight --address http://localhost:5681 --token "$TOKEN" -o ./audit

Point -o at an extract context directory to have migrate pick the result up.

Audit the Global and every zone. On a Global, the audit also reads each zone's settings as the zone reported them over KDS.

What it needs

Item Detail
Token Read access to the API. On Kong Mesh, /config (the CP settings) is access-controlled: the GENERATE_DATAPLANE_TOKEN access type on 2.x, VIEW_CONTROL_PLANE_METADATA on 3.0. Without it the settings are not audited and the report is inconclusive
Latest 2.x patch Read from the kumahq/kuma releases (one GitHub API request). Set --latest-version 2.14.7 to skip the request, for example without internet access. Without a value the version check does not run and the report is inconclusive
Envoy inspection Off by default. --inspect-dataplanes N (--preflight-inspect-dataplanes on extract) fetches up to N config dumps, one request per proxy

On Konnect the Global's own settings and version are managed by Kong, so the audit treats the control plane as a Global, skips those two, and audits every zone. The read-only token is enough. The Konnect path has not yet been run against a real Konnect organization.

Reading the result

The terminal shows the status and every blocker. The HTML report has the details, examples named by KRI, coverage gaps and the manual checks the API cannot answer.

Status Meaning
clean No blocker, every check ran
blockers At least one blocker, every check ran
inconclusive At least one check could not run (coverage gap). Blockers may be listed too
failed The audit could not run: unreachable address, not a Kuma API. The command exits non-zero

preflight exits 0 whenever a report is produced, blockers included, so read the status rather than the exit code.

The migrate report adds a Live Control Plane Audit section per context directory that has a v3-preflight.json, on both targets: status, control plane, counts, the blocker table and the coverage gaps. See Output and reports.

Flags

See CLI reference.