MeshIdentity

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, you 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

This resource is namespaced (system-namespace only) and controls how data plane proxies receive identity certificates.

Spec fields

Selector

The selector field controls which data plane proxies a MeshIdentity applies to. It uses Kubernetes-style label selectors on data plane proxy tags.

When multiple MeshIdentity resources apply to the same data plane proxy, the one with the most specific selector (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 alphabetically takes precedence.

Data plane

Specifies the label selector for matching data plane proxies.

SPIFFE ID

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

Trust domain

Template for constructing the SPIFFE ID trust domain. The trust domain is the root of a SPIFFE identity namespace and identifies the trust boundary within which identities are valid.

Supported variables:

• .Mesh - The mesh name
• .Zone - The zone name
• {{ label "label-name" }} - Any label from the data plane proxy resource

Path

Template for constructing the SPIFFE ID path component. The path provides additional specificity to identify a workload within a trust domain.

Supported variables:

• .Namespace - The Kubernetes namespace
• .ServiceAccount - The Kubernetes service account
• .Workload - The workload identifier
• {{ label "label-name" }} - Any label from the data plane proxy resource

When using .Workload in the path template, data plane proxies selected by this MeshIdentity must have the workload identifier. This can be provided either:

• Via a data plane proxy token generated with the --workload parameter
• Directly on the data plane proxy resource via the kuma.io/workload label

Connections from data plane proxies lacking the required workload identifier will be rejected.

Provider

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

Type

Specifies the type of certificate provider.

Bundled

Configuration for certificates generated by Kuma’s control plane, either automatically generated or supplied by the user. Required when type is Bundled.

Mesh trust creation

Defines whether a MeshTrust resource should be automatically created from this MeshIdentity. When Enabled, the control plane automatically generates a MeshTrust resource with the same name as this MeshIdentity.

Insecure allow self-signed

Allows the use of self-signed certificates. This should only be enabled in development environments or when you understand the security implications.

Auto-generate

Configuration for automatic CA generation by the control plane.

Enabled

When true, the control plane automatically generates a self-signed CA and stores it. This is useful for testing and development.

Certificate authority

Configuration for user-provided certificate authority. Use this to specify a custom CA instead of automatic generation.

Certificate

Data source containing the CA certificate. The control plane resolves this data source at runtime. Supported data source types include File, Secret (Kubernetes), and Inline.

Private key

Data source containing the CA private key. The control plane resolves this data source at runtime. Supported data source types include File, Secret (Kubernetes), and Inline.

Certificate parameters

Parameters for certificate generation.

Expiry

Duration for which generated certificates are valid.

SPIRE

Configuration for SPIRE-based certificate delivery. Required when type is Spire. To enable SPIRE socket injection, either:

• Set KUMA_RUNTIME_KUBERNETES_INJECTOR_SPIRE_ENABLED environment variable on the control plane globally
• Enable it per pod by adding the k8s.kuma.io/spire-support label

Agent

Configuration for the SPIRE agent.

Timeout

Connection timeout to the socket exposed by the SPIRE agent.

Examples

Basic MeshIdentity with automatic generation

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: Enabled
      insecureAllowSelfSigned: true
      autogenerate:
        enabled: true

type: MeshIdentity
name: identity
mesh: default
spec:
  selector:
    dataplane:
      matchLabels: {}
  provider:
    type: Bundled
    bundled:
      meshTrustCreation: Enabled
      insecureAllowSelfSigned: true
      autogenerate:
        enabled: true

MeshIdentity with custom SPIFFE ID

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity
  namespace: {{site.mesh_namespace}}
  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

type: MeshIdentity
name: identity
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

MeshIdentity with user-provided certificate authority

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplane:
      matchLabels:
        app: my-app
  provider:
    type: Bundled
    bundled:
      meshTrustCreation: Enabled
      insecureAllowSelfSigned: true
      ca:
        certificate:
          type: File
          file:
            path: /ca.crt
        privateKey:
          type: File
          file:
            path: /ca.key

type: MeshIdentity
name: identity
mesh: default
spec:
  selector:
    dataplane:
      matchLabels:
        app: my-app
  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

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity-spire
  namespace: {{site.mesh_namespace}}
  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:
      agent:
        timeout: 2s

type: MeshIdentity
name: identity-spire
mesh: default
spec:
  selector:
    dataplane:
      matchLabels: {}
  spiffeID:
    trustDomain: default.us-east.mesh.local
    path: "/ns/{{ .Namespace }}/sa/{{ .ServiceAccount }}"
  provider:
    type: Spire
    spire:
      agent:
        timeout: 2s

MeshIdentity with workload label

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity-workload
  namespace: {{site.mesh_namespace}}
  labels:
    kuma.io/mesh: default
spec:
  selector:
    dataplane:
      matchLabels: {}
  spiffeID:
    trustDomain: "{{ .Mesh }}.{{ .Zone }}.mesh.local"
    path: "/workload/{{ .Workload }}"
  provider:
    type: Bundled
    bundled:
      meshTrustCreation: Enabled
      insecureAllowSelfSigned: true
      autogenerate:
        enabled: true

type: MeshIdentity
name: identity-workload
mesh: default
spec:
  selector:
    dataplane:
      matchLabels: {}
  spiffeID:
    trustDomain: "{{ .Mesh }}.{{ .Zone }}.mesh.local"
    path: "/workload/{{ .Workload }}"
  provider:
    type: Bundled
    bundled:
      meshTrustCreation: Enabled
      insecureAllowSelfSigned: true
      autogenerate:
        enabled: true

See also

• MeshTrust - Configure trust between different domains
• MeshTLS - Configure TLS modes and ciphers
• MeshTrafficPermission (experimental) - Control traffic access with SPIFFE
• Issuing Identity with MeshIdentity bundled provider - Guide for using MeshIdentity with bundled provider
• Issuing Identity with MeshIdentity and Spire - Guide for using MeshIdentity with Spire

All options