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

constraints object → Constraints
Constraints to apply to the mesh and its entities
Requirements defines a set of requirements that data plane proxies must fulfill in order to join the...
tags object
Tags defines set of required tags. You can specify '*' in value to require non empty value of tag
Restrictions defines a set of restrictions that data plane proxies cannot fulfill in order to join t...
tags object
Tags defines set of required tags. You can specify '*' in value to require non empty value of tag
logging object → Logging
List of available logging backends
conf object
Configuration of the backend
format string
Format of access logs. Placeholders available on https://www.envoyproxy.io/docs/envoy/latest/configu...
name string
Name of the backend, can be then used in Mesh.logging.defaultBackend or in TrafficLogging
type string
Type of the backend (Kuma ships with 'tcp' and 'file')
defaultBackend string
Name of the default backend
meshServices object → MeshServices
mode enum
Values: Disabled | Everywhere | ReachableBackends | Exclusive
metrics object → Metrics
Metrics defines configuration for metrics that should be collected and exposed by dataplanes.
List of available Metrics backends
conf object
Configuration of the backend
name string
Name of the backend, can be then used in Mesh.metrics.enabledBackend
type string
Type of the backend (Kuma ships with 'prometheus')
enabledBackend string
Name of the enabled backend
mtls object → Mtls
mTLS settings of a Mesh.
List of available Certificate Authority backends
conf object
Configuration of the backend
DpCert defines settings for certificates generated for Dataplanes
requestTimeout string
Timeout on request to CA for DP certificate generation and retrieval
Rotation defines rotation settings for Dataplane certificate
expiration string
Time after which generated certificate for Dataplane will expire
mode enum
Values: STRICT | PERMISSIVE
name string
Name of the backend
RootChain defines settings related to CA root certificate chain.
requestTimeout string
Timeout on request for to CA for root certificate chain. If not specified, defaults to 10s.
type string
Type of the backend. Has to be one of the loaded plugins (Kuma ships with builtin and provided)
enabledBackend string
Name of the enabled backend
skipValidation boolean
If enabled, skips CA validation.
networking object → Networking
Networking defines the networking configuration of the mesh
Outbound describes the common mesh outbound settings
passthrough boolean
Control the passthrough cluster
routing object → Routing
Routing defines configuration for the routing in the mesh
defaultForbidMeshExternalServiceAccess boolean
If true, blocks traffic to MeshExternalServices. Default: false
localityAwareLoadBalancing boolean
Enable the Locality Aware Load Balancing
zoneEgress boolean
Enable routing traffic to services in other zone or external services through ZoneEgress. Default: f...
skipCreatingInitialPolicies array
List of policies to skip creating by default when the mesh is created. e.g. TrafficPermission, MeshR...
tracing object → Tracing
Tracing defines tracing configuration of the mesh.
List of available tracing backends
conf object
Configuration of the backend
name string
Name of the backend, can be then used in Mesh.tracing.defaultBackend or in TrafficTrace
sampling number
Percentage of traces that will be sent to the backend (range 0.0 - 100.0). Empty value defaults to 1...
type string
Type of the backend (Kuma ships with 'zipkin')
defaultBackend string
Name of the default backend