Transformation examples
Before-and-after YAML for each migration scenario, as produced by the current release.
Every output below was produced by running kuma-migrator migrate on the input shown. Warnings
printed alongside are summarised in prose. The full behaviour per kind is on the
policy pages.
Scenario: Legacy
# Before
type: Timeout
mesh: default
name: my-timeout
sources:
- match:
kuma.io/service: '*'
destinations:
- match:
kuma.io/service: backend_demo_svc_3001
conf:
connectTimeout: 5s
# After (--to-latest v2)
mesh: default
name: my-timeout
spec:
targetRef:
kind: Mesh
to:
- default:
connectionTimeout: 5s
targetRef:
kind: MeshService
name: backend
namespace: demo
type: MeshTimeout
Under --to-latest v3 the destination is selected by labels, because 3.0 selects real
resources by labels only:
# After (--to-latest v3)
mesh: default
name: my-timeout
spec:
targetRef:
kind: Mesh
to:
- default:
connectionTimeout: 5s
targetRef:
kind: MeshService
labels:
k8s.kuma.io/namespace: demo
kuma.io/display-name: backend
type: MeshTimeout
Scenario: Subset
# Before
apiVersion: kuma.io/v1alpha1
kind: MeshTrafficPermission
metadata:
namespace: kong-mesh-system
name: allow-backend-to-redis
spec:
targetRef:
kind: MeshSubset
tags:
k8s.kuma.io/service-name: redis
from:
- targetRef:
kind: MeshSubset
tags:
kuma.io/service: backend_demo_svc_3001
default:
action: Allow
# After (--to-latest v2)
apiVersion: kuma.io/v1alpha1
kind: MeshTrafficPermission
metadata:
name: allow-backend-to-redis
namespace: kong-mesh-system
spec:
from:
- default:
action: Allow
targetRef:
kind: MeshService
labels:
k8s.kuma.io/namespace: demo
kuma.io/display-name: backend
targetRef:
kind: Dataplane
name: redis
namespace: kong-mesh-system
The from[] source lives in namespace demo, which differs from the policy namespace, so it is
selected by labels. The top-level k8s.kuma.io/service-name: redis carries no namespace, so the
policy namespace is used and the reference keeps the name/namespace form.
Warning:
Dataplanewithnameselects theDataplaneobject of that name. On Kubernetes a Dataplane is named after its Pod (redis-7d9c…), not after the service. Check that the reference matches your Dataplanes before applying, or select them by label.
Under --to-latest v3 the top-level reference becomes labels, because 3.0 selects by labels
only:
# After (--to-latest v3), spec.targetRef
targetRef:
kind: Dataplane
labels:
app: redis
k8s.kuma.io/namespace: kong-mesh-system
app is a best guess for the Pod label and is reported as a warning. Both targets warn that
from[] on MeshTrafficPermission is deprecated in favour of rules[] and is not converted;
see Access control.
Scenario: Rules
# Before
apiVersion: kuma.io/v1alpha1
kind: MeshTimeout
metadata:
name: backend-timeout
spec:
targetRef:
kind: Dataplane
labels:
app: backend
from:
- targetRef:
kind: Mesh
default:
idleTimeout: 30s
# After (both targets)
apiVersion: kuma.io/v1alpha1
kind: MeshTimeout
metadata:
name: backend-timeout
spec:
rules:
- default:
idleTimeout: 30s
targetRef:
kind: Dataplane
labels:
app: backend
The rules[] entry applies to all inbound traffic selected by spec.targetRef. A from[]
entry whose source is not kind: Mesh is narrower than that, and the conversion warns about the
widened scope.
Scenario: Gateway (MeshGatewayRoute to HTTPRoute)
MeshHTTPRoute and MeshTCPRoute are passed through unchanged; only the built-in gateway's
MeshGatewayRoute is converted. Same output on both targets. The backend lives in another
namespace than the route, so a ReferenceGrant is generated in the backend namespace.
# Before
apiVersion: kuma.io/v1alpha1
kind: MeshGatewayRoute
metadata:
name: edge
namespace: gateways
labels:
kuma.io/mesh: default
spec:
selectors:
- match:
kuma.io/service: edge_gateways_svc
conf:
http:
rules:
- matches:
- path: {match: PREFIX, value: /}
backends:
- weight: 1
destination:
kuma.io/service: api_apps_svc_8080
# After: HTTPRoute-gateways-edge.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
labels:
kuma.io/mesh: default
name: edge
namespace: gateways
spec:
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: edge
rules:
- backendRefs:
- group: ""
kind: Service
name: api
namespace: apps
port: 8080
weight: 1
matches:
- path:
type: PathPrefix
value: /
# After: ReferenceGrant-apps-gateways-edge.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
name: gateways-edge
namespace: apps
spec:
from:
- group: gateway.networking.k8s.io
kind: HTTPRoute
namespace: gateways
to:
- group: ""
kind: Service
name: api
Scenario: Mesh under --to-latest v3
A Mesh using the legacy mTLS backend in permissive mode, with outbound passthrough on:
# Before
apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
name: default
spec:
mtls:
enabledBackend: ca-1
backends:
- name: ca-1
type: builtin
mode: PERMISSIVE
networking:
outbound:
passthrough: true
routing:
zoneEgress: true
# After (--to-latest v3): Mesh-default.yaml
apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
name: default
spec:
meshServices:
mode: Exclusive
# After (--to-latest v3): MeshTLS-kong-mesh-system-default-tls-permissive.yaml
apiVersion: kuma.io/v1alpha1
kind: MeshTLS
metadata:
labels:
kuma.io/mesh: default
name: default-tls-permissive
namespace: kong-mesh-system
spec:
rules:
- default:
mode: Permissive
targetRef:
kind: Mesh
# After (--to-latest v3): MeshPassthrough-kong-mesh-system-default-passthrough.yaml
apiVersion: kuma.io/v1alpha1
kind: MeshPassthrough
metadata:
labels:
kuma.io/mesh: default
name: default-passthrough
namespace: kong-mesh-system
spec:
default:
passthroughMode: All
targetRef:
kind: Mesh
spec.mtls and routing.zoneEgress are gone from the Mesh. The run prints a blocking
warning for spec.mtls: create a MeshIdentity (and MeshTrust) that selects every proxy
before upgrading, or the mesh serves plaintext on 3.0. Under --to-latest v2 the same input
keeps spec.mtls and routing.zoneEgress, gains meshServices.mode: Exclusive, drops
networking.outbound.passthrough: true (the 2.x default), and reports the 3.0 changes as
advisories. See Meshes and mTLS and identity.
Scenario: ExternalService
Universal input from a kumactl extraction. Same output on both targets.
# Before
type: ExternalService
mesh: default
name: httpbin
tags:
kuma.io/service: httpbin
kuma.io/protocol: http
networking:
address: httpbin.org:443
tls:
enabled: true
# After: MeshExternalService-httpbin.yaml
mesh: default
name: httpbin
spec:
endpoints:
- address: httpbin.org
port: 443
match:
port: 443
protocol: http
type: HostnameGenerator
tls:
enabled: true
verification:
mode: Secured
type: MeshExternalService
The run warns that verification.mode defaults to Secured, that match.port copies the
endpoint port, and that the hostname clients use now comes from a HostnameGenerator. Under
--to-latest v3 it also warns when the input has no MeshIdentity for the mesh: 3.0 requires
one for MeshExternalService traffic. See External services.
Scenario: OPAPolicy (Kong Mesh)
# Before
apiVersion: kuma.io/v1alpha1
kind: OPAPolicy
metadata:
name: my-opa-policy
namespace: kong-mesh-system
spec:
targetRef:
kind: Mesh
conf:
policies:
- inlineString: |
package envoy.authz
default allow = false
allow { input.attributes.request.http.method == "GET" }
# After (--to-latest v2)
apiVersion: kuma.io/v1alpha1
kind: MeshOPA
metadata:
name: my-opa-policy
namespace: kong-mesh-system
spec:
default:
appendPolicies:
- rego:
inlineString: |-
package envoy.authz
default allow = false
allow { input.attributes.request.http.method == "GET" }
targetRef:
kind: Mesh
Under --to-latest v3 the rego source uses the SecureDataSource shape that Kong Mesh 3.0
requires:
# After (--to-latest v3), spec.default
default:
appendPolicies:
- rego:
insecureInline:
value: |-
package envoy.authz
default allow = false
allow { input.attributes.request.http.method == "GET" }
type: InsecureInline
See MeshOPA.