Extract
Pull resources out of a running Kuma or Kong Mesh control plane, and the control plane mode rules that decide what is kept.
extract reads every writable Kuma resource from a control plane and writes one YAML file per
resource. The output directory is the input of migrate. extract only reads:
it never writes to the control plane.
Connection modes
--kube-context |
--kumactl-context |
|
|---|---|---|
| Tool | kubectl |
kumactl CLI, or direct HTTPS for Konnect |
| Type discovery | Every kuma.io/v1alpha1 CRD in the cluster |
GET <cp>/_resources |
| Listing | kubectl get <plural> -A -o json per CRD |
kumactl get <type> [--mesh <mesh>] -o yaml per type and mesh |
| Mode detection | KUMA_MODE on the control plane Deployment in kuma-system or kong-mesh-system |
GET <cp>/config |
| Zone federation | KUMA_MULTIZONE_ZONE_GLOBAL_ADDRESS and KUMA_MULTIZONE_ZONE_NAME on the Deployment |
multizone.zone.globalAddress and multizone.zone.name in GET <cp>/config |
| Environment | Kubernetes skip list always; KUMA_ENVIRONMENT and KUMA_STORE_TYPE recorded |
environment and store.type fields of GET <cp>/config |
| Output format | Kubernetes, as returned by the API server | Universal by default; --output-format kubernetes converts it |
| Apply command in the report | kubectl apply -f <dir>/ |
one kumactl apply -f <file> per file |
Both paths exclude kinds whose name contains Insight, and kinds in the skip list (see
Configuration file).
The --kumactl-context path resolves the context from ~/.kumactl/config (or
$KUMACTL_CONFIG). When $KUMACTL_CONFIG is set, every kumactl call gets
--config-file $KUMACTL_CONFIG: kumactl itself only reads ~/.kumactl/config. It ignores the
readOnly flag that /_resources returns: a control plane with ApiServer.ReadOnly=true
reports every type as read-only, which would extract nothing. extract never writes through
that API, so the flag does not apply to it.
Generated resources
Resources the control plane generates and reconciles itself are skipped in every mode and
counted after extraction. They carry a kuma.io/managed-by label:
| Value | Resource |
|---|---|
k8s-controller |
MeshService generated from a Kubernetes Service; MeshZoneAddress; Workload |
meshservice-generator |
MeshService generated from Dataplane inbounds on Universal |
workload-generator |
Workload on Universal |
A hand-written MeshService has no such label and is extracted. The kuma.io/env label does
not tell the two apart: Kuma sets it on every MeshService created on a zone.
Server-written fields
extract drops the fields the server writes, so each file can be applied again as it is:
| Format | Dropped | Why |
|---|---|---|
| both | status |
computed by the control plane; migrate does not read it |
| Kubernetes | metadata.resourceVersion |
a stale value makes kubectl apply fail with a conflict |
| Kubernetes | metadata.uid, creationTimestamp, generation, selfLink, managedFields, deletionTimestamp, deletionGracePeriodSeconds |
owned by the API server |
| Kubernetes | metadata.ownerReferences |
Kuma's mutating webhook adds the Mesh owner on create, with the UID of the Mesh in the target cluster. A copied reference carries the source cluster's UID: anywhere else, the garbage collector deletes the object as orphaned. Kuma 3.0 also rejects a Mesh owner that disagrees with the resource's mesh |
| Kubernetes | annotation kubectl.kubernetes.io/last-applied-configuration |
written by client-side kubectl apply |
| Universal | creationTime, modificationTime, kri |
computed by the control plane |
Labels and other annotations are kept, including the kuma.io/* labels the control plane
computes: the zone filter and migrate read them.
Code: pkg/extractor/kube.go,
pkg/extractor/kumactl.go.
Output layout
<output-dir>/
<context>-global-ctx/ ← context name + control plane mode
.kuma-migrator.json ← how this context was extracted
mesh-default/ ← one directory per mesh, prefixed "mesh-"
resiliency/
routing/
zero-trust/
observability/
mesh/
other/
mesh-prod/
resiliency/
mesh/Mesh-prod.yaml ← a Mesh goes under its own directory
global-scoped-resources/ ← resources with no mesh (Zone, HostnameGenerator, …)
other/
<context>-zone-ctx/ ← a Zone control plane
mesh-default/
resiliency/
<context>-standalone-ctx/
<context>-unknown-ctx/ ← mode could not be detected
The kind subfolders come from
pkg/resource/subfolder.go:
| Subfolder | Kinds |
|---|---|
resiliency |
MeshCircuitBreaker, MeshRetry, MeshTimeout, MeshHealthCheck, MeshRateLimit, MeshFaultInjection and their legacy equivalents |
routing |
MeshHTTPRoute, MeshTCPRoute, MeshLoadBalancingStrategy, MeshPassthrough, MeshService, MeshExternalService, MeshMultiZoneService, the gateway kinds, ExternalService, TrafficRoute, VirtualOutbound |
zero-trust |
MeshTrafficPermission, MeshTLS, MeshIdentity, MeshTrust, MeshOPA, TrafficPermission, OPAPolicy, Secret, GlobalSecret |
observability |
MeshMetric, MeshTrace, MeshAccessLog, TrafficLog, TrafficTrace |
mesh |
Mesh, MeshProxyPatch, ProxyTemplate |
other |
everything else |
.kuma-migrator.json records the extraction:
{"tool":"kumactl","context":"konnect-global-prod","cpMode":"global","isKonnect":true,"environment":"kubernetes"}
{"tool":"kubectl","context":"zone-eu-west1-prod","cpMode":"zone","environment":"kubernetes","storeType":"kubernetes","federated":true}
migrate reads it to pick the skip list (environment), to write the right apply command
(tool, context, isKonnect) into the report, and, under --to-latest v3, to check the
control plane topology (cpMode, environment, storeType, federated; see
Upgrade plans). Without it, the report assumes
kubectl and skips the topology check. federated is written for zone control planes only.
Extract one mesh only:
kuma-migrator extract --kumactl-context global-cp --output-dir ./raw-policies --mesh default
The mesh of a resource is its kuma.io/mesh label, or the top-level mesh field: Universal
format stores it there, and so do the Kubernetes CRDs of the legacy kinds (TrafficPermission,
MeshGatewayRoute, …), which carry no label. A Mesh belongs to itself and is written to
mesh-<name>/mesh/; --mesh keeps only that mesh's Mesh. migrate also reads the older
layout, where Mesh files sit under global-scoped-resources/mesh/.
Running extract against several control planes with the same --output-dir is supported:
each control plane gets its own <context>-<mode>-ctx/ directory.
Control plane modes
extract detects the mode of the control plane and filters on the kuma.io/origin label.
The mode decides both the directory suffix and the filter. For a zone control plane, the filter
also depends on whether the zone is federated, that is, connected to a Global control plane.
| Mode | Directory | Kept | Skipped |
|---|---|---|---|
global |
<context>-global-ctx |
kuma.io/origin: global and resources with no origin label |
kuma.io/origin: zone (read-only copies synced up from zones), listed after extraction with the zone to target; MeshGatewayInstance and MeshGatewayConfig |
zone, federated |
<context>-zone-ctx |
kuma.io/origin: zone and resources with no origin label (created on the zone, counted after extraction) |
kuma.io/origin: global (copies synced from the Global control plane; extract them there), counted after extraction |
zone, not federated |
<context>-zone-ctx |
everything | nothing |
standalone |
<context>-standalone-ctx |
everything | nothing |
| unknown | <context>-unknown-ctx |
everything | nothing |
A zone counts as federated when it has both a Global address and a zone name, the same test as
Kuma's IsFederatedZoneCP. The Helm chart always sets KUMA_MULTIZONE_ZONE_GLOBAL_ADDRESS in
zone mode, empty when controlPlane.kdsGlobalAddress is unset, so extract checks the value.
Kuma 3.0 removes the standalone mode: it becomes zone. The two already behave the same,
and a 2.x control plane started with KUMA_MODE=standalone already reports zone through
GET /config, so the --kumactl-context path sees it as a non-federated zone. extract keeps
the -standalone-ctx directory name for a control plane that the --kube-context path still
reads as standalone, so existing extract directories stay valid.
The filter is implemented in
pkg/extractor/extractor.go.
Kuma's multizone resource sync is described in the
Kuma multizone docs.
Global control plane
Extract the Global control plane first:
# kumactl path
kuma-migrator extract --kumactl-context global-cp --output-dir ./raw-policies
# or the kubectl path, same control plane
kuma-migrator extract --kube-context global-cp --output-dir ./raw-policies
Console output on a Global control plane:
CP mode: global
Attached zones: zone-eu-west, zone-us-east
[INFO] MeshGatewayInstance and MeshGatewayConfig are zone-local and skipped here.
Run extract against each Zone CP to capture gateway instances.
Found 24 writable resource type(s)
Extracted 83 resource(s) to ./raw-policies
⚠ Zone-origin resources skipped on Global CP — extract from their zone instead:
MeshTimeout/my-timeout → zone: zone-eu-west
MeshRateLimit/rate-limit-svc → zone: zone-us-east
Zone control planes
Zone control planes hold what the Global control plane does not:
- resources created on the zone: producer policies, namespace-scoped consumer policies, anything applied directly to the zone cluster;
MeshGatewayInstanceandMeshGatewayConfig, which are never synced to the Global control plane.
kuma-migrator extract --kube-context prod-zone-eu --output-dir ./raw-policies
kuma-migrator extract --kube-context prod-zone-us --output-dir ./raw-policies
Console output on a federated Zone control plane:
CP mode: zone (eu-west), federated
[WARN] Extracting from a federated Zone CP — copies synced from Global (kuma.io/origin: global) are skipped.
For a complete policy set, also run extract against the Global CP.
[INFO] Resources created on this zone are extracted: kuma.io/origin: zone, or no origin label
(Kuma 2.x does not label legacy policies, ExternalService, ProxyTemplate, MeshGatewayRoute, …).
Extracted 12 resource(s) to ./raw-policies
[INFO] 4 resource(s) without a kuma.io/origin label kept (created on this zone): ExternalService 1, TrafficPermission 3
[INFO] 31 resource(s) synced from the Global CP (kuma.io/origin: global) skipped — extract them from the Global CP.
Only kuma.io/origin: global marks a synced copy. The Global-to-zone sync (KDS) sets it on
every resource it writes (pkg/kds/context/context.go in Kuma). kuma.io/origin: zone is set
by Kuma's defaulting webhook, which the 2.x Helm chart registers for the new-style policies,
Mesh, Dataplane, MeshGateway and the zone proxies only. The legacy policies,
ExternalService, ProxyTemplate, MeshGatewayRoute, OPAPolicy, AccessRole and
AccessAudit never get the label on Kubernetes, and a resource created before Kuma 2.7 may
lack it too. Both were created on the zone, so extract keeps them.
Zone control plane without a Global
A zone control plane that is not connected to a Global control plane (KUMA_MODE=zone with no
Global address) owns every resource in its store, including those with no origin label, so
extract applies no origin filter:
CP mode: zone (eu-west), not federated
[INFO] This Zone CP is not connected to a Global CP: every resource in its store is its own.
No kuma.io/origin filter is applied — all resources are extracted.
Where gateway resources live
| Kind | Created on | Global extraction | Zone extraction |
|---|---|---|---|
MeshGateway, MeshGatewayRoute, MeshHTTPRoute, MeshTCPRoute |
Global (usual) | extracted | skipped (kuma.io/origin: global) |
MeshGateway, MeshGatewayRoute, MeshHTTPRoute, MeshTCPRoute |
Zone | not present | extracted (kuma.io/origin: zone or no origin label) |
MeshGatewayInstance, MeshGatewayConfig |
Zone only | skipped | extracted, with or without an origin label |
any policy with kuma.io/origin: zone |
Zone, synced read-only to Global | skipped, warning printed | extracted |
Environment detection
The --kumactl-context path reads environment (kubernetes or universal) from
GET <cp>/config, prints it, and records it in .kuma-migrator.json. 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.
The --kube-context path always uses the Kubernetes skip list. It records the Deployment's
KUMA_ENVIRONMENT and KUMA_STORE_TYPE in .kuma-migrator.json (the Helm chart sets both to
kubernetes; a Global control plane deployed with controlPlane.environment: universal on
PostgreSQL reports otherwise), which the 3.0 topology check reads.
If GET <cp>/config fails, extract prints a warning and continues in unknown mode: no origin
filter, Kubernetes skip list. On Kong Mesh 3.0, /config requires the
VIEW_CONTROL_PLANE_METADATA access type, so a 401 or 403 here usually means the role
behind the kumactl context lacks it. Check it with kumactl get access-roles -o yaml.
Konnect
A control plane URL containing api.konghq.com is treated as Kong Konnect:
- Authentication.
kumactlstores a Konnect personal access token as a header (Authorization: Bearer kpat_…) instead ofauthType: tokens.extractreads both forms. A system account token (spat_…) with read-only access is enough; see Konnect read-only access. - Mode. Konnect has no
/configendpoint; it is always treated as a Global control plane. - Fetching. Meshes, zones and resources are read with direct authenticated HTTPS calls to
the Konnect API, not through the
kumactlbinary. - Format. Konnect list endpoints return Universal format (
{total, items: [...]}) regardless of the requested format.--output-format kubernetesconverts each item.
Readiness audit
With --kumactl-context, --preflight runs the Kong Mesh 3.0 readiness audit against the same
control plane after the files are written, and saves v3-preflight.json and
v3-preflight.html in the context directory. migrate summarises them. See
Live control plane audit.
Universal format
kumactl and Konnect return Universal format: type, name and mesh at the top level, no
apiVersion or metadata. extract handles both single resources and
{total: N, items: [...]} lists. By default the files keep Universal format.
--output-format kubernetes converts them: type becomes kind, name becomes
metadata.name, mesh becomes the kuma.io/mesh label, and the control-plane-only fields
(kri, creationTime, modificationTime) are dropped. Documents that are already in
Kubernetes format are not changed.
migrate reads both formats.
Self-hosted kumactl specifics
/_resources returns each type's API path, not its kumactl subcommand. The two are the same
for every type except HealthCheck: API path health-checks, subcommand healthchecks.
extract maps it. If kumactl still has no subcommand for a type (it answers
unknown flag: --mesh, or prints its usage), extract warns and reads that type from the
control plane API directly, following the pages. A type that fails does not stop the remaining
types.
Use -k / --tls-skip-verify, or adminServer.tlsSkipVerify: true in the configuration
file, for a control plane API with a self-signed certificate.