Mesh Identity

This resource is experimental. It requires MeshService to be enabled. It works on Kubernetes since version 2.12, and on Universal since version 2.13.

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 Kong Mesh 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.

The following example shows the full structure:

apiVersion: kuma.io/v1alpha1
kind: MeshIdentity
metadata:
  name: identity
  namespace: kong-mesh-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

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

MeshIdentity controls how data plane proxies receive identity certificates. The following key fields define how identities are issued and applied:

• 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 matchLabels selectors on data plane proxy tags. You can 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, Kong Mesh compares their names lexicographically. The policy whose name comes first in alphabetical order takes precedence.

Examples

The following table contains examples of the selector field with different scopes:

spec:
  selector:
    dataplane:
      matchLabels: {}

spec:
  selector:
    dataplane:
      matchLabels:
        app: my-app

spec:
  selector: {}

SPIFFE ID

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

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

spec:
  spiffeID:
    trustDomain: "{{ .Mesh }}.{{ .Zone }}.mesh.local"
    path: "/workload/{{ .Workload }}"

Supported variables in the trustDomain field are:

• .Mesh
• .Zone

Supported variables in the path field are:

• .Namespace - The Kubernetes namespace
• .ServiceAccount - The Kubernetes service account
• .Workload - The workload identifier

You can also use resource labels in both trustDomain and path, for example:

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" }}'

Workload label requirement v2.13+

When using {{ label "kuma.io/workload" }} or {{ .Workload }} in the path template, data plane proxies selected by this MeshIdentity must have the kuma.io/workload label. This label can be provided either:

• Via a data plane proxy token generated with the --workload parameter
• Directly on the data plane proxy resource

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

Here’s an example using the workload identifier in the path:

spec:
  spiffeID:
    trustDomain: '{{ .Mesh }}.{{ .Zone }}.mesh.local'
    path: '/workload/{{ label "kuma.io/workload" }}'

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 Kong Mesh’s control plane, either autogenerated or supplied by the user.
• Spire: Certificates are issued directly by a SPIRE Agent through SDS.