MeshService
Moving policies, routes and workload addresses from kuma.io/service tags to MeshService, and setting meshServices.mode before Kuma 3.0.
On 2.x a destination is identified by the kuma.io/service tag of its inbounds — on
Kubernetes a generated value such as backend_demo_svc_3001. MeshService
replaces it with a real resource that has a name, a namespace, ports and a hostname, and that
lives in one zone. On 3.0 kuma.io/service-based destinations are gone: unified resource
naming is unconditional and the meshServices switch has no effect.
What changed upstream
| Version | Change |
|---|---|
| 2.8 | MeshService spec.ports[].protocol renamed to appProtocol; HostnameGenerator templates applied to MeshServices (CHANGELOG) |
| 2.9 | MeshService generation controlled by Mesh.spec.meshServices.mode (CHANGELOG) |
| 2.10 | Names of Mesh, MeshService, MeshExternalService and MeshMultiZoneService that are not RFC 1035 labels are deprecated (UPGRADE) |
| 2.14 | HostnameGenerator templates validated at creation (RFC 1123 subdomain); MeshMultiZoneService names over 63 characters deprecated (UPGRADE) |
| 3.0 | meshServices has no effect; unified naming is unconditional. The field stays as deprecated so stored values keep syncing to 2.x zones. 3.0 rejects any mode other than Exclusive (UPGRADE) |
| 3.0 | Policies select MeshService by labels only (UPGRADE) |
| 3.0 | MeshService spec.selector.dataplaneTags removed: a write that still carries it is rejected (spec.selector.dataplaneTags: unknown field), and a stored one loses its selector and matches no proxies (UPGRADE) |
| 3.0 | MeshService spec.identities[] accepts SPIFFE IDs only (type: ServiceTag rejected) (UPGRADE) |
| 3.0 | appProtocol on MeshService and MeshMultiZoneService ports accepts only tcp, http, http2 and grpc: Kafka is no longer a protocol (kumahq/kuma#17831). On 2.x kafka was a TCP proxy plus Envoy's kafka_broker filter, which only emits stats |
| 3.0 | Non-RFC 1035 names rejected (UPGRADE) |
| 3.0 | reachableServices removed; reachableBackends refs select by labels only; a transparent-proxy data plane without reachableBackends gets no outbounds (UPGRADE) |
The upstream migration guide is the "Migration" section of the MeshService docs.
meshServices.mode
| Mode | Behaviour on 2.x |
|---|---|
Disabled |
No MeshService generation. A Mesh with no meshServices block resolves to this |
Everywhere |
MeshServices generated; both kuma.io/service and MeshService produce Envoy clusters (about twice the resources) |
ReachableBackends |
MeshServices generated but only configured on a proxy that lists them in reachableBackends. kuma.io/service stays fully active. Use it to migrate consumer by consumer |
Exclusive |
Only MeshService, MeshExternalService and MeshMultiZoneService. kuma.io/service matching is off |
Only Exclusive turns kuma.io/service off. On 3.0 every mesh behaves as Exclusive. Because a
2.x zone reads a missing field as Disabled and then deletes every generated MeshService,
Exclusive must be stored on every mesh before the Global CP is upgraded. Drop the field once
every zone runs 3.0.
What kuma-migrator does
The Subset scenario rewrites kuma.io/service and k8s.kuma.io/service-name selectors
(convert.go). A
Kubernetes kuma.io/service value <name>_<namespace>_svc_<port> is decoded into name,
namespace and port; a Universal value is used as the name.
| Input | --to-latest v2 |
--to-latest v3 |
|---|---|---|
spec.targetRef MeshSubset with kuma.io/service: '*' |
kind: Mesh |
Same |
spec.targetRef MeshSubset with a service tag |
kind: Dataplane with labels: {app: <name>, k8s.kuma.io/namespace: <ns>} plus other tags, in every namespace (never name: a Dataplane name is its pod's name); app is a best guess and warned |
Same |
Kuma-reserved tag that is not a label (kuma.io/protocol, kuma.io/instance, k8s.kuma.io/service-port, …) next to a service tag |
Dropped from the generated labels, with a warning naming it. kuma.io/zone, kuma.io/env, kuma.io/mesh, kuma.io/origin, k8s.kuma.io/namespace are labels and are kept |
Same |
to[]/from[] MeshSubset with a service tag |
kind: MeshService with name/namespace (same namespace as the policy) or labels (system namespace, other tags) |
kind: MeshService with labels only |
from[] MeshSubset with a service tag on MeshTrafficPermission/MeshFaultInjection |
Kept: it is the form the 2.7 notes give in place of the deprecated MeshService |
As above; a policy still carrying from[] is rejected by 3.0 and written to _manual/ |
MeshService ref with a Kuma-internal name (backend_demo_svc_3001) |
Decoded: to[]/from[] → MeshService name/namespace (sectionName kept); top level → Dataplane labels. On MeshTrafficPermission/MeshFaultInjection from[] → MeshSubset with that kuma.io/service tag |
Same, with labels |
Universal-format policy (type/name/mesh at the root) |
Converted in place: the Universal layout and every unrelated field are kept | Same |
rules[] and to[] in one policy |
Split: rules[] keeps the name, to[] goes to <name>-outbound |
Same |
Mesh |
meshServices.mode: Exclusive injected, with a warning to migrate policies and workloads first |
Same, with the mixed-version note |
MeshService ports[].protocol |
Renamed to appProtocol |
Same |
MeshService selector.dataplaneTags |
Advisory | Rewritten to dataplaneLabels.matchLabels; a kuma.io/-prefixed tag is not converted (reserved label prefix), and the MeshService is written to _manual/ because 3.0 rejects it |
MeshService identities[] type: ServiceTag |
Advisory | Entry dropped |
MeshService / MeshMultiZoneService ports[].appProtocol: kafka |
Advisory | Rewritten to tcp; only the Kafka stats are lost |
Dataplane reachableServices |
Warning | Converted to reachableBackends refs with labels where the value decodes; warned otherwise |
reachableBackends ref by name/namespace |
— | Rewritten to labels |
Non-RFC 1035 Mesh/MeshService/MeshExternalService/MeshMultiZoneService name |
Warning | Warning |
HostnameGenerator template that renders an invalid DNS subdomain |
Warning | Warning |
Deployment/StatefulSet env var holding <svc>_<ns>_svc_<port>.mesh |
Listed in the report's address mapping, with the Kubernetes and .mesh replacements |
Same |
reachableBackends and dataplaneTags are rewritten under v3 only: on 2.14 a labels selector
also matches same-named services synced from other zones, so the rewrite would widen selection.
What it cannot do
- Know the pod labels. A top-level
kuma.io/serviceselector becomesDataplanelabels withapp: <name>. Most charts setapp, but the tool cannot check. Every such case is warned. - Choose between
MeshServiceandMeshMultiZoneService. AMeshServiceis one zone's service. If clients relied onkuma.io/serviceload-balancing across zones, they need a MeshMultiZoneService, which you create. See Multizone. - Check label refinements. A
MeshSubsetthat combined a service tag with another tag (for exampleversion: v2) becomes aMeshServiceselected bykuma.io/display-name,k8s.kuma.io/namespaceandversion: v2. TheMeshServiceonly matches if it carries that label, which comes from the KubernetesService, not from the pods. - Find the MeshService port of a Universal outbound or a
reachableServicesentry whose name does not decode. - Rename resources. A name that is not an RFC 1035 label must be renamed, which changes the hostname and every reference to it.
Manual steps
- On 2.14, set
meshServices.mode: ReachableBackends(gradual) orEverywhereon each mesh. - For every consumer of a
kuma.io/servicedestination, decideMeshService(one zone) orMeshMultiZoneService(all zones), and create theMeshMultiZoneServices. - Apply the
v2output: policies and routes that refer toMeshService. - Update workload addresses listed in the report's address mapping (for example
backend_demo_svc_3001.mesh→backend.demo.svc.cluster.local:3001). - Fill
reachableBackendson transparent-proxy data planes (required on 3.0). - Set
meshServices.mode: Exclusive. This must be stored before the Global CP upgrade. - Rename resources the report flags as non-RFC 1035.
- Before upgrading, run
--to-latest v3and apply the labels-only selectors and thedataplaneLabelsselectors.
Example
Input — two files: a policy still on MeshSubset, and one partially migrated
(kind: MeshService with the Kuma-internal name):
apiVersion: kuma.io/v1alpha1
kind: MeshTimeout
metadata:
name: web-to-backend
namespace: kong-mesh-system
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: MeshSubset
tags:
kuma.io/service: web_demo_svc_8080
to:
- targetRef:
kind: MeshSubset
tags:
kuma.io/service: backend_demo_svc_3001
version: v2
default:
http:
requestTimeout: 5s
---
apiVersion: kuma.io/v1alpha1
kind: MeshRetry
metadata:
name: web-retry
namespace: demo
labels:
kuma.io/mesh: default
spec:
targetRef:
kind: Mesh
to:
- targetRef:
kind: MeshService
name: backend_demo_svc_3001
default:
http:
numRetries: 2
Output with --to-latest v2:
# resiliency/MeshTimeout-kong-mesh-system-web-to-backend.yaml
apiVersion: kuma.io/v1alpha1
kind: MeshTimeout
metadata:
labels:
kuma.io/mesh: default
name: web-to-backend
namespace: kong-mesh-system
spec:
targetRef:
kind: Dataplane
labels:
app: web
k8s.kuma.io/namespace: demo
to:
- default:
http:
requestTimeout: 5s
targetRef:
kind: MeshService
labels:
k8s.kuma.io/namespace: demo
kuma.io/display-name: backend
version: v2
# resiliency/MeshRetry-demo-web-retry.yaml
apiVersion: kuma.io/v1alpha1
kind: MeshRetry
metadata:
labels:
kuma.io/mesh: default
name: web-retry
namespace: demo
spec:
targetRef:
kind: Mesh
to:
- default:
http:
numRetries: 2
targetRef:
kind: MeshService
name: backend
namespace: demo
With --to-latest v3 the MeshTimeout is identical (it already uses labels) and the MeshRetry
destination becomes a label selector. The MeshRetry is a producer policy (its to[] names a
service in its own namespace), and 3.0 keeps it one only if the selector also carries
kuma.io/zone; the input has no kuma.io/zone label, so a warning names the selector to add
kuma.io/zone: <zone-name> to (see Policy targeting):
# resiliency/MeshRetry-demo-web-retry.yaml (v3)
targetRef:
kind: MeshService
labels:
k8s.kuma.io/namespace: demo
kuma.io/display-name: backend
Warning on both targets:
⚠ spec.targetRef Dataplane labels use 'app: web' as a best-guess pod label — verify this
matches your actual pod labels before applying
A Universal MeshService still selecting by dataplaneTags: {kuma.io/service: backend} is
not rewritten under v3, because kuma.io/service cannot be a Dataplane label. 3.0 rejects
it as written, so it goes to _manual/:
⚠ MeshService "backend": spec.selector.dataplaneTags is removed in 3.0 — a 3.0 control plane
rejects the MeshService as written (unknown field), so it is kept out of the apply tree. Not
converted: kuma.io/service=backend cannot be a Dataplane label (reserved kuma.io/ prefix), and
dropping it would widen the selector. …
Related
- Policy targeting — labels-only selection and policy roles
- Multizone —
MeshMultiZoneService - Dataplanes —
reachableServicesandreachableBackends - Meshes