Policies · Other resources

Mesh

Mesh-wide settings: mTLS backends, legacy observability backends, routing and networking defaults.

Kuma

Behaviour per target

--to-latest v2 (2.x) rewritten

Output: Mesh, MeshMetric, MeshPassthrough

Rewritten when it has observability sections, sets networking.outbound.passthrough, or does not set meshServices.mode: Exclusive:

  • spec.metrics is removed. Its enabledBackend turns metrics on for every proxy, so that backend becomes a companion MeshMetric <mesh>-metrics with targetRef: Mesh. Backends that are not enabled are dropped; no enabledBackend means no MeshMetric. The MeshMetric keeps what the backend published: sidecar.profiles.appendProfiles: [All] and includeUnused (from envoy.usedOnly), because a MeshMetric without them publishes only the Basic profile and only metrics that changed; aggregate[] → applications[]; tls.mode: delegated → ProvidedTLS. envoy.filterRegex is reported, not converted. When the endpoint required a mesh client certificate (mesh mTLS on, skipMTLS false), a warning says no 2.x MeshMetric mode keeps that check, so the endpoint becomes plaintext. See Observability.
  • spec.tracing and spec.logging are 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-wide MeshTrace/MeshAccessLog would turn tracing/logging on for every proxy. The warning lists which backends a TrafficLog/TrafficTrace in the input references and which none does (those were inactive, nothing is lost).
  • networking.outbound.passthrough: false becomes a MeshPassthrough <mesh>-passthrough with passthroughMode: None.
  • spec.meshServices.mode: Exclusive is injected: 3.0 requires it, and a 2.x zone reads a missing field as Disabled.
  • networking.outbound.passthrough: true is removed (it is the 2.x default) with a warning to add a MeshPassthrough with passthroughMode: All before 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.

--to-latest v3 (3.0) rewritten

Output: Mesh, MeshMetric, MeshTLS, MeshPassthrough

v2 rewrites, plus:

  • spec.mtls is removed with a blocking warning: create a MeshIdentity (and MeshTrust) covering every proxy before upgrading, or the mesh serves plaintext and MeshTLS/MeshTrafficPermission stop applying.
  • A PERMISSIVE enabled backend generates a MeshTLS <mesh>-tls-permissive with rules[].default.mode: Permissive.
  • outbound.passthrough: true generates a MeshPassthrough <mesh>-passthrough with passthroughMode: All. When the field is unset, a warning explains that 3.0 defaults to None.
  • routing.zoneEgress, routing.localityAwareLoadBalancing, routing.defaultForbidMeshExternalServiceAccess, skipCreatingInitialPolicies and constraints are deleted. For constraints the 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: Exclusive is 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 as Disabled and deletes its generated MeshServices). 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

VersionChange
2.10Names that are not RFC 1035 labels deprecated.
2.12MeshIdentity + MeshTrust introduced as the successor to spec.mtls.
3.0mtls, 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.

Source files