Kuma Star

MeshIdentity

This resource is experimental. It works only on Kubernetes and requires MeshServices to be enabled.

Overview

MeshIdentity is a resource that defines how workloads in a mesh obtain their cryptographic identity. It separates the responsibility of issuing identities from establishing trust, enabling Kuma to adopt SPIFFE compliant practices while remaining flexible and easy to use.

With MeshIdentity, users can:

  • Enable secure mTLS between services, using trusted certificate authorities.
  • Switch identity providers without downtime, for example when migrating from built-in certificates to Spire.
  • Assign different identity providers to subsets of workloads, allowing more granular control.

A basic example follows to illustrate the structure:

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplane:
      matchLabels: {}
  spiffeID:
    trustDomain: "{{ .Mesh }}.{{ .Zone }}.mesh.local"
    path: "/ns/{{ .Namespace }}/sa/{{ .ServiceAccount }}"
  provider:
    type: Bundled
    bundled:
      meshTrustCreation: Enabled
      insecureAllowSelfSigned: true
      certificateParameters:
        expiry: 24h
      autogenerate:
        enabled: true

Configuration

MeshIdentity is a namespaced (system-namespace only) resource that controls how data plane proxies receive identity certificates. It is composed of a few key fields that control how identities are issued and applied. In the following sections, each field is explained in detail with examples:

  • Selector – which data plane proxies this identity applies to.
  • SpiffeID – how the SPIFFE ID is constructed (trust domain and path).
  • Provider – which system issues the certificates (Bundled or Spire).

Selector

The selector field controls which data plane proxies a MeshIdentity applies to. It uses a Kubernetes-style label selector on data plane proxy tags. This makes it possible to scope an identity to all workloads, a subset of workloads, or none at all.

When multiple MeshIdentity resources apply to the same data plane proxy, the one with the most specific selector (the greatest number of matching labels) takes precedence. If two policies have selectors with the same number of labels, Kuma compares their names lexicographically. The policy whose name comes first in alphabetical order takes precedence (for example, aaa is chosen over bbb).

Examples

Apply to all data plane proxies
spec:
  selector:
    dataplane:
      matchLabels: {}
Apply to a group of data plane proxies
spec:
  selector:
    dataplane:
      matchLabels:
        app: my-app
Apply to nothing
spec:
  selector: {}

SpiffeID

The spiffeID field lets you override how SPIFFE IDs are constructed for the data plane proxies selected by this MeshIdentity. By default, Kuma generates a SPIFFE ID based on the mesh and zone. With spiffeID, you can customize the trustDomain and the path template.

spec:
  spiffeID:
    trustDomain: "{{ .Mesh }}.{{ .Zone }}.mesh.local"
    path: "/ns/{{ .Namespace }}/sa/{{ .ServiceAccount }}"

Supported variables in trustDomain field are:

  • .Mesh
  • .Zone

Supported variables in path field are:

  • .Namespace
  • .ServiceAccount

Also, both in trustDomain and path it’s possible to use resource’s labels, i.e.:

spec:
  spiffeID:
    trustDomain: '{{ label "kuma.io/mesh" }}.{{ label "kuma.io/zone" }}.mesh.local'
    path: '/ns/{{ label "k8s.kuma.io/namespace" }}/sa/{{ label "k8s.kuma.io/service-account" }}'

Provider

The provider field defines how identity certificates are issued. This field is required and must specify one of the supported provider types:

  • Bundled – certificates are issued by Kuma’s control plane, either autogenerated or supplied by the user.
  • Spire – certificates are issued directly by a SPIRE Agent through SDS.

Examples

Minimal Bundled MeshIdentity

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplane:
      matchLabels: {}
  provider:
    type: Bundled
    bundled:
      meshTrustCreation: Disabled
      insecureAllowSelfSigned: true
      autogenerate:
        enabled: true

MeshIdentity with CA provided by user

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplane:
      matchLabels:
        app: my-app
  spiffeID:
    trustDomain: "{{ .Mesh }}.{{ .Zone }}.mesh.local"
    path: "/ns/{{ .Namespace }}/sa/{{ .ServiceAccount }}"
  provider:
    type: Bundled
    bundled:
      meshTrustCreation: Enabled
      insecureAllowSelfSigned: true
    ca:
      certificate:
        type: File
        file:
          path: "/ca.crt"
      privateKey:
        type: File
        file:
          path: "/ca.key"

MeshIdentity with Spire provider

To enable Spire socket injection, you can either:

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity-spire
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplane:
      matchLabels: {}
  spiffeID:
    trustDomain: default.us-east.mesh.local
    path: "/ns/{{ .Namespace }}/sa/{{ .ServiceAccount }}"
  provider:
    type: Spire
    spire: {}