Using Trust Manager¶

Trust Manager is designed to be lightweight and purpose-driven, introducing a single Kubernetes Custom Resource Definition (CRD) called Bundle.

A Bundle defines a collection of X.509 certificates to be distributed across the cluster. All Bundles are cluster-scoped resources.

Each Bundle specifies one or more sources that Trust Manager uses to assemble the final trust bundle, along with a target configuration that defines how and where the resulting bundle is published within the cluster.

Sample bundle:

apiVersion: trust.cert-manager.io/v1alpha1
kind: Bundle
metadata:
  name: my-org.com  # The bundle name will also be used for the target
spec:
  sources:
  # Include a bundle of publicly trusted certificates which can be
  # used to validate most TLS certificates on the internet, such as
  # those issued by Let's Encrypt, Google, Amazon and others.
  # NB: Unless you pin the package providing these CAs, the default can change!
  - useDefaultCAs: true

  # A Secret in the "trust" namespace; see "Trust Namespace" below for further details
  - secret:
      name: "my-db-tls"
      key: "ca.crt"

  # Another Secret source, but this time using a label selector instead of a named Secret
  - secret:
      selector:
        matchLabels:
          fruit: apple
      key: "ca.crt"

  # One more Secret source, this time including all certificates from every key
  - secret:
      name: "my-regional-cas"
      includeAllKeys: true

  # A ConfigMap in the "trust" namespace; see "Trust Namespace" below for further details
  - configMap:
      name: "my-org.net"
      key: "root-certs.pem"

  # Another ConfigMap source, but this time using a label selector instead of a named ConfigMap
  - configMap:
      selector:
        matchLabels:
          fruit: apple
      key: "ca.crt"

  # One more ConfigMap source, this time including all certificates from every key
  - configMap:
      name: "my-org-cas"
      includeAllKeys: true

  # A manually specified PEM-encoded cert, included directly into the Bundle
  - inLine: |
      -----BEGIN CERTIFICATE-----
      MIIC5zCCAc+gAwIBAgIBADANBgkqhkiG9w0BAQsFADAVMRMwEQYDVQQDEwprdWJl
      ....
      0V3NCaQrXoh+3xrXgX/vMdijYLUSo/YPEWmo
      -----END CERTIFICATE-----
  target:
    # Sync the bundle to a ConfigMap called `my-org.com` in every namespace which
    # has the label "linkerd.io/inject=enabled"
    # All ConfigMaps will include a PEM-formatted bundle, here named "root-certs.pem"
    # and in this case we also request binary formatted bundles in JKS and PKCS#12 formats,
    # here named "bundle.jks" and "bundle.p12".
    configMap:
      key: "root-certs.pem"
      metadata:
        annotations:
          argocd.argoproj.io/sync-wave: "1"
        labels:
          app.kubernetes.io/component: "trust-bundle"
    additionalFormats:
      jks:
        key: "bundle.jks"
      pkcs12:
        key: "bundle.p12"
    namespaceSelector:
      matchLabels:
        linkerd.io/inject: "enabled"

For more information about bundles and sources, see the Trust Manager API reference.

Bundle Source Types¶

Bundle resources support several source types:

• ConfigMap – References a ConfigMap resource in the Trust Manager namespace.
• Secret – References a Secret resource in the Trust Manager namespace.
• inLine – Contains a manually specified string with one or more certificates.
• useDefaultCAs – Includes a predefined bundle of publicly trusted root certificates.

Key and Certificate Handling¶

Both ConfigMap and Secret sources support defining a specific data key (key) that contains at least one certificate, or alternatively using the includeAllKeys option to include all certificates from every key in the resource.

Using includeAllKeys is especially useful in dynamic environments where key names are determined at runtime.

Resource Selection¶

ConfigMap and Secret sources also support label selectors to select multiple resources at once.
This is valuable in dynamic environments where the resource name may not be known until runtime.

Example Use Case¶

These features can be combined.
For example, you can configure a source to:

• Select all Secrets with a specific label.
• Include every certificate from each key within those Secrets.

This approach simplifies trust distribution in dynamic, large-scale Kubernetes environments.

Bundle Targets¶

By default, ConfigMap is the target type for Bundle resources.
Starting with v0.7.0, Trust Manager also supports using Secret resources as targets.

Target Behavior¶

All Bundle targets are written to ConfigMaps (and/or Secrets) that share the same name as the Bundle.
Each target contains a PEM-formatted trust bundle.

Annotations and labels for target ConfigMaps or Secrets can be defined in the following fields:

• spec.target.configMap.metadata.annotations
• spec.target.configMap.metadata.labels

Replace configMap with secret when configuring Secret targets.

Additional Trust Store Formats¶

Trust Manager can optionally write binary trust stores in additional formats:

• JKS – supported since v0.5.0
• PKCS#12 – supported since v0.7.0

Applications consuming JKS or PKCS#12 trust stores often require a password for legacy reasons.
These passwords generally provide little security benefit — many implementations use weak encryption or store passwords alongside the encrypted files.

Default passwords are:

Customizing Trust Store Passwords¶

You can customize the passwords for these bundles using the following fields in your Bundle specification:

• spec.target.additionalFormats.jks.password
• spec.target.additionalFormats.pkcs12.password

This allows you to set custom passwords if required by your organization’s policy or application behavior.

Namespace selector¶

A target’s namespaceSelector defines which Namespaces a Bundle target should be synced to.
This allows fine-grained control over where trust bundles are distributed within the cluster.

The namespaceSelector supports the matchLabels field, which can be used to match Namespaces based on their labels.

Default Behavior¶

If namespaceSelector is left empty, the Bundle target will currently be synced to all Namespaces in the cluster.

What's next?¶

• Quick start: Creating Your First Bundle