Kuma Star

Careful!

You are browsing documentation for the next version of Kuma. Use this version at your own risk.

Mesh

The Mesh resource defines a service mesh instance. It is the parent resource of all other Kuma 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.

Kuma creates a default mesh automatically on startup. Disable this by setting KUMA_DEFAULTS_SKIP_MESH_CREATION=true.

Spec fields

Field Description
mtls mTLS configuration with CA backends. See Mutual TLS.
networking.outbound.passthrough Allow traffic to unknown destinations. Default: true. See Non-mesh traffic.
routing.zoneEgress Route cross-zone/external traffic through ZoneEgress. See Zone Egress.
routing.localityAwareLoadBalancing Prefer endpoints in same zone. See MeshLoadBalancingStrategy.
routing.defaultForbidMeshExternalServiceAccess Block MeshExternalService traffic by default.
constraints.dataplaneProxy Control which proxies can join mesh. See DP membership.
skipCreatingInitialPolicies Skip default policy creation. Use ['*'] to skip all.
meshServices.mode MeshService generation: Disabled, Everywhere, ReachableBackends, Exclusive. See MeshService.

When mTLS is enabled, all traffic is denied unless MeshTrafficPermission allows it.

Examples

Basic mesh

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

Mesh with mTLS enabled (builtin CA)

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)

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 (for migration):

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. Use 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 mesh to specific zones in multizone 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

See also

All options