Home / Kong Mesh
Edit
Report

Mesh resource

Uses: Kong Mesh
Related Documentation
Mesh Documentation
Tags
#mtls #service-mesh
Related Resources
Configuring your mesh and multi-tenancy
Mutual TLS
Data plane proxy membership
Non-mesh traffic
Zone Egress
MeshService

The Mesh resource defines a service mesh instance and is the parent resource of all other Kong Mesh resources, including data plane proxies and policies.

Create multiple meshes to isolate services by team, environment, or security requirements. Each data plane proxy belongs to exactly one mesh.

Kong Mesh creates a default mesh automatically on startup. To disable automatic creation, set KUMA_DEFAULTS_SKIP_MESH_CREATION=true.

On Kubernetes, a single namespace cannot contain pods from multiple meshes. To enforce one mesh per namespace, enable runtime.kubernetes.disallowMultipleMeshesPerNamespace. For details, see the namespace-mesh constraint.

Configuration reference

The following fields configure mTLS, networking, routing, membership, and service generation for a Mesh resource:

Field

Description
mtls Configures mTLS with CA backends. See Mutual TLS.
networking.outbound.passthrough Allows traffic to unknown destinations. Default: true. See Non-mesh traffic.
routing.zoneEgress Routes cross-zone and external traffic through ZoneEgress. See Zone Egress.
routing.localityAwareLoadBalancing Prefers endpoints in the same zone. See MeshLoadBalancingStrategy.
routing.defaultForbidMeshExternalServiceAccess Blocks MeshExternalService traffic by default.
constraints.dataplaneProxy Controls which proxies can join the mesh. See Data plane proxy membership.
skipCreatingInitialPolicies Skips default policy creation. Set to ['*'] to skip all policies.
meshServices.mode Controls MeshService generation. Options: Disabled, Everywhere, ReachableBackends, Exclusive. See MeshService.

When you enable mTLS, Kong Mesh denies all traffic unless a MeshTrafficPermission policy allows it.

Examples

The following examples show common Mesh configurations for both Kubernetes and Universal deployments.

Basic mesh

Define a minimal mesh with no additional configuration:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default

Mesh with mTLS enabled (built-in CA)

Enable mTLS using a built-in certificate authority that Kong Mesh generates and rotates automatically:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  mtls:
    enabledBackend: ca-1
    backends:
      - name: ca-1
        type: builtin
        dpCert:
          rotation:
            expiration: 24h
        conf:
          caCert:
            RSAbits: 2048
            expiration: 10y

Mesh with mTLS (provided CA)

Enable mTLS using your own root certificate and key, stored in secrets:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  mtls:
    enabledBackend: ca-1
    backends:
      - name: ca-1
        type: provided
        dpCert:
          rotation:
            expiration: 24h
        conf:
          cert:
            secret: my-ca-cert
          key:
            secret: my-ca-key

Mesh with permissive mTLS mode

Accept both mTLS and plaintext traffic during a migration to mTLS:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  mtls:
    enabledBackend: ca-1
    backends:
      - name: ca-1
        type: builtin
        mode: PERMISSIVE

PERMISSIVE mode is not secure because it accepts plaintext traffic. Use it only during migration, then switch to STRICT.

Mesh with ZoneEgress routing

Route cross-zone and external traffic through ZoneEgress:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  routing:
    zoneEgress: true

Mesh with passthrough disabled

Block traffic to unknown destinations:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  networking:
    outbound:
      passthrough: false

Mesh without default policies

Skip all default policy creation:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  skipCreatingInitialPolicies: ['*']

Mesh with namespace restrictions (Kubernetes)

Allow only pods from specific namespaces:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  constraints:
    dataplaneProxy:
      requirements:
        - tags:
            k8s.kuma.io/namespace: team-a
        - tags:
            k8s.kuma.io/namespace: team-b

Mesh with zone segmentation

Restrict the mesh to specific zones in a multi-zone deployment:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: production
spec:
  constraints:
    dataplaneProxy:
      requirements:
        - tags:
            kuma.io/zone: us-east
        - tags:
            kuma.io/zone: us-west
      restrictions:
        - tags:
            env: development

Mesh with MeshServices enabled

Enable automatic MeshService generation:

apiVersion: kuma.io/v1alpha1
kind: Mesh
metadata:
  name: default
spec:
  meshServices:
    mode: Exclusive

Schema

Something wrong?
Report an Issue | Edit this Page
View all Kong documentation

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help?

Ask in our Slack Community
Contact Support