Policies · Other resources
Mesh
Mesh-wide settings: mTLS backends, legacy observability backends, routing and networking defaults.
Behaviour per target
Output: Mesh, MeshMetric, MeshPassthrough
Rewritten when it has observability sections, sets networking.outbound.passthrough, or
does not set meshServices.mode: Exclusive:
spec.metricsis removed. ItsenabledBackendturns metrics on for every proxy, so that backend becomes a companionMeshMetric<mesh>-metricswithtargetRef: Mesh. Backends that are not enabled are dropped; noenabledBackendmeans noMeshMetric. TheMeshMetrickeeps what the backend published:sidecar.profiles.appendProfiles: [All]andincludeUnused(fromenvoy.usedOnly), because aMeshMetricwithout them publishes only the Basic profile and only metrics that changed;aggregate[]→applications[];tls.mode: delegated→ProvidedTLS.envoy.filterRegexis reported, not converted. When the endpoint required a mesh client certificate (mesh mTLS on,skipMTLSfalse), a warning says no 2.xMeshMetricmode keeps that check, so the endpoint becomes plaintext. See Observability.spec.tracingandspec.loggingare removed without a companion. On 2.x they only declare backends: a TrafficTrace or TrafficLog activates one, and its conversion carries the backend inline. A mesh-wideMeshTrace/MeshAccessLogwould turn tracing/logging on for every proxy. The warning lists which backends aTrafficLog/TrafficTracein the input references and which none does (those were inactive, nothing is lost).networking.outbound.passthrough: falsebecomes aMeshPassthrough<mesh>-passthroughwithpassthroughMode: None.spec.meshServices.mode: Exclusiveis injected: 3.0 requires it, and a 2.x zone reads a missing field asDisabled.networking.outbound.passthrough: trueis removed (it is the 2.x default) with a warning to add aMeshPassthroughwithpassthroughMode: Allbefore 3.0.
Kept, with advisories: spec.mtls (the move to MeshIdentity + MeshTrust is a CA
cutover, not a rewrite; the advisory is specific to the backend type: builtin names the
ca-builtin-* Secrets to reuse from a Bundled MeshIdentity, provided names its
conf.cert/conf.key DataSources, and Kong Mesh vault/acmpca/cert-manager name
their Extension provider), a PERMISSIVE mTLS backend,
routing.defaultForbidMeshExternalServiceAccess, routing.zoneEgress,
routing.localityAwareLoadBalancing, skipCreatingInitialPolicies, constraints (the
data plane proxy membership rules, not enforced on 3.0). Names that are not RFC 1035
labels are reported.
Output: Mesh, MeshMetric, MeshTLS, MeshPassthrough
v2 rewrites, plus:
spec.mtlsis removed with a blocking warning: create aMeshIdentity(andMeshTrust) covering every proxy before upgrading, or the mesh serves plaintext andMeshTLS/MeshTrafficPermissionstop applying.- A
PERMISSIVEenabled backend generates aMeshTLS<mesh>-tls-permissivewithrules[].default.mode: Permissive. outbound.passthrough: truegenerates aMeshPassthrough<mesh>-passthroughwithpassthroughMode: All. When the field is unset, a warning explains that 3.0 defaults toNone.routing.zoneEgress,routing.localityAwareLoadBalancing,routing.defaultForbidMeshExternalServiceAccess,skipCreatingInitialPoliciesandconstraintsare deleted. Forconstraintsthe warning lists the requirements and restrictions that stop being enforced (3.0 has no membership check) and the nearest control: dataplane tokens bound to the mesh and tags.meshServices.mode: Exclusiveis kept. A 3.0 control plane accepts it with the deprecation warning "meshServices was removed in 3.0 and is ignored"; that is expected. The field is needed while any zone runs 2.x (a 2.x zone reads a missing field asDisabledand deletes its generatedMeshServices). Drop it once every zone runs 3.0. See Meshes.
Companion policies keep the format of the Mesh: Universal input gives Universal
documents (type/name/mesh), Kubernetes input gives CRDs in the system namespace
(see Meshes).
Timeline
| Version | Change |
|---|---|
| 2.10 | Names that are not RFC 1035 labels deprecated. |
| 2.12 | MeshIdentity + MeshTrust introduced as the successor to spec.mtls. |
| 3.0 | mtls, tracing, logging, routing.zoneEgress, routing.localityAwareLoadBalancing, routing.defaultForbidMeshExternalServiceAccess, networking.outbound.passthrough, constraints and skipCreatingInitialPolicies removed. meshServices has no effect but must be Exclusive. Non-RFC 1035 names rejected. |
Related topics
- Meshes — Every field of the Mesh resource that changed between 2.x and 3.0, and what kuma-migrator does with each one.
- mTLS and workload identity — Moving a mesh from Mesh.mtls to MeshIdentity and MeshTrust before Kuma 3.0, and why kuma-migrator reports it instead of rewriting it.
- Observability — Metrics, tracing and access logs from Mesh fields and legacy policies to MeshMetric, MeshTrace, MeshAccessLog and MeshOpenTelemetryBackend.
- MeshService — Moving policies, routes and workload addresses from kuma.io/service tags to MeshService, and setting meshServices.mode before Kuma 3.0.