Kuma Star

Careful!

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

MeshTrust

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

MeshTrust is a resource that defines certificate authority (CA) bundles for validating encrypted mTLS traffic from different trust domains. It separates trust establishment from identity issuance, enabling mesh applications to accept mTLS connections authenticated by external or cross-zone certificate authorities.

Overview

When workloads communicate across trust boundaries—such as between zones in a multizone deployment, or when accepting traffic from external systems—they need trusted CA certificates to validate incoming connections. MeshTrust provides these CA bundles to the mesh.

Key capabilities:

  • Enable cross-zone mTLS communication in multizone deployments
  • Accept encrypted traffic from applications running outside the mesh
  • Deploy gateways without requiring sidecar proxies
  • Manage multiple trust domains within a single mesh

Autogenerated MeshTrust

MeshIdentity resources automatically create corresponding MeshTrust resources when meshTrustCreation: Enabled is configured. These autogenerated resources can be identified by the origin field in the specification, which contains a kri reference to the source MeshIdentity.

Example of an autogenerated MeshTrust:

spec:
  trustDomain: default.zone-1.mesh.local
  caBundles:
    - type: Pem
      pem:
        value: |-
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
  origin:
    kri: kri_mid_default_default_kuma-system_my-identity_

Multizone deployments

In multizone deployments, each zone has a different trust domain by default to increase security. This means cross-zone traffic requires manual configuration. To enable cross-zone mTLS communication, manually copy or create MeshTrust resources containing the CA certificates from other zones.

For example, to allow zone-1 workloads to accept traffic from zone-2:

  1. Export the CA certificate from zone-2’s autogenerated MeshTrust resource or from zone-2’s MeshIdentity CA configuration
  2. Create a MeshTrust resource in zone-1 containing zone-2’s CA bundle
  3. Set the trustDomain to match zone-2’s trust domain

Limitations

When using SPIRE as the identity provider, MeshTrust does not apply because SPIRE directly manages trust establishment through its own federation mechanisms.

Spec fields

trustDomain

The trust domain associated with this MeshTrust resource. This value must match the trust domain of the certificates being validated.

Type: string Required: Yes Max length: 253 characters

Example: default.zone-2.mesh.local

caBundles

A list of certificate authority bundles that can validate certificates from the specified trust domain. At least one CA bundle must be provided.

Type: array Required: Yes Min items: 1

Each CA bundle contains:

type

The format of the CA bundle. Currently only Pem is supported.

Type: string (enum: Pem) Required: Yes

pem

Contains the PEM-encoded certificate authority bundle when type is set to Pem.

Type: object Required: When type is Pem
value

The PEM-encoded CA certificates as a string. Multiple certificates can be concatenated.

Type: string Required: Yes

origin

Indicates whether this MeshTrust was automatically created from a MeshIdentity resource. This field is set by the system and typically should not be manually configured.

Type: object Required: No

kri

Resource identifier referencing the source MeshIdentity that created this MeshTrust.

Type: string Required: No

Examples

Manual MeshTrust for cross-zone traffic

apiVersion: kuma.io/v1alpha1
kind: MeshTrust
metadata:
  name: zone-2-trust
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
    kuma.io/origin: zone
    kuma.io/zone: zone-1
spec:
  trustDomain: default.zone-2.mesh.local
  caBundles:
    - type: Pem
      pem:
        value: |-
          -----BEGIN CERTIFICATE-----
          MIIDdjCCAl6gAwIBAgICEAEwDQYJKoZIhvcNAQELBQAwRDELMAkGA1UEBhMCR0Ix
          EDAOBgNVBAgMB0VuZ2xhbmQxEjAQBgNVBAoMCUFsaWNlIEx0ZDEPMA0GA1UEAwwG
          S3VtYUNBMB4XDTIxMDUxMjEzMzU1MVoXDTMxMDUxMDEzMzU1MVowUDELMAkGA1UE
          BhMCR0IxEDAOBgNVBAgMB0VuZ2xhbmQxEjAQBgNVBAoMCUFsaWNlIEx0ZDEbMBkG
          A1UEAwwSS3VtYUludGVybWVkaWF0ZUNBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
          MIIBCgKCAQEA1VzY9vOr8+SINzqA8Rwk4bpeex32Zn9BGAUTweRgomQC7Yfzrm6/
          Vk74/T/46n3FydpdEZTdoFKCF8EsA0eqAEfWi6tu7D41GOUFUYpdRJBJEq+HE17Q
          N8SFMquy8NhCtK8th8ytSu2ThvCOq1MHT5WjtQUmRGSJMlcfWA5TsCIK0Sb3cSf3
          jadjEqcmcvJN6Xa0Y0VivcPg5eB+We7BNnp4ogqmZw0veoPjc14HVZpqxrra9Yez
          DRai6rnHqDjnkMMhe9MmSkCKD9Ldwduq0ZfuOQFIBOaX+4MKUyDN4tTMCcRRl/Nl
          A4JgrNNWCFfUQV0VmQ0Tc8+cn/+gokHAZwIDAQABo2YwZDAdBgNVHQ4EFgQUGNjz
          Te727HX4AqZDMn1L9XzkTaYwHwYDVR0jBBgwFoAUSu2E4Ue5aPzdWQCCNp36Pf3i
          YbcwEgYDVR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAQYwDQYJKoZIhvcN
          AQELBQADggEBACuOczJlf4wcT9rfAIrZHuI5aCzYTKOxJllhN5e/eEhMYpsox6Zb
          4CZXS3wdJ3fVugddLWDzIAjrNE1DrOpugUPurNIpHsT6u+SHFXkRsXyHFfMA+CZJ
          0tOYEtP1r3BnqsY/nh0GJqHJxaJolEaqFaKgKTQPTinOxTKFxsHa1OHlsvkdxvot
          d2BQhPQYWes3LMPxtGhS5kwKaXaB3gzTnzjGvgGNeJ+l0AiWqXkivixpox3/6mMa
          90mwssl4sRQQLR1kLFU4hwghNm52Pk7o7HSTEXsnB+ZhHB9skpetY6R4uKWh8xap
          Xmj4PDrAA5OKZzSO7Yhdt0vXPOIrjShMxvA=
          -----END CERTIFICATE-----

Certificate chain

apiVersion: kuma.io/v1alpha1
kind: MeshTrust
metadata:
  name: external-trust
  namespace: kuma-system
  labels:
    kuma.io/mesh: default
spec:
  trustDomain: external.example.com
  caBundles:
    - type: Pem
      pem:
        value: |-
          -----BEGIN CERTIFICATE-----
          ... (Root CA certificate) ...
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          ... (Intermediate CA certificate) ...
          -----END CERTIFICATE-----

See also

All options

kind string
Kind is a string value representing the REST resource this object represents. Servers may infer this...
spec object
Spec is the specification of the Kuma MeshTrust resource.
Origin specifies whether the resource was created from a MeshIdentity.
kri string
Resource identifier
CABundles contains a list of CA bundles supported by this TrustDomain. At least one CA bundle must b...
Pem contains the PEM-encoded CA bundle if the Type is set to a PEM-based format.
value string required
Value holds the PEM-encoded CA bundle as a string.
type enum required
Type specifies the format or source type of the CA bundle.
Values: Pem
trustDomain string required
TrustDomain is the trust domain associated with this resource.
metadata object
apiVersion string
APIVersion defines the versioned schema of this representation of an object. Servers should convert ...