Wiki · Concept · Last reviewed June 25, 2026

Kubernetes ClusterTrustBundle

Kubernetes ClusterTrustBundle is a cluster-scoped container for distributing X.509 trust anchors to workloads.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, certificates, trust anchors, X.509, AI governance

Definition

Kubernetes ClusterTrustBundle is a cluster-scoped API object for X.509 trust anchors, commonly root certificates. The generated Kubernetes API reference describes the v1beta1 object as a container for trust anchors and says its spec.trustBundle field holds PEM-wrapped, DER-formatted X.509 certificates. Kubernetes certificate documentation marks cluster trust bundles as beta in Kubernetes v1.33 and disabled by default.

Trust anchors answer a different question than certificates. A certificate says a particular key and name were issued by a signer. A trust bundle tells a workload which issuing authorities it should trust when validating certificates. KEP-3257 frames ClusterTrustBundle as the missing in-tree mechanism for certificate signers to communicate their trust anchors to workloads.

How It Works

A ClusterTrustBundle can be signer-linked or signer-unlinked. A signer-linked bundle sets spec.signerName, uses a name prefixed from that signer name, and is meant to carry trust anchors for that signer. The API reference says creating or updating a signer-linked object requires the cluster-scoped attest verb on the matching signers resource. A signer-unlinked bundle leaves spec.signerName empty and is controlled by ordinary access rules for the object.

The API validates the trust material. The documented requirements include valid X.509 certificates wrapped in PEM certificate blocks, CA basic constraints, rejection of duplicate certificates, and no PEM block headers. Consumers, including kubelet, may reorder or deduplicate certificate blocks according to their own logic.

ClusterTrustBundles are intended to be broadly readable inside the cluster. Kubernetes documentation says they should be considered world-readable within the cluster, and that all ServiceAccounts get default read access under RBAC. Their contents can also be projected into a container filesystem through the clusterTrustBundle projected volume source when the relevant feature support is enabled.

Agent Context

AI infrastructure often chains together model gateways, evaluation workers, vector stores, tool servers, service meshes, private registries, observability pipelines, and admission controllers. Those components may not share the public Web PKI. They may need to trust private cluster signers, internal gateways, or workload identities issued by a platform signer.

ClusterTrustBundle matters because it makes trust distribution a Kubernetes object rather than an image-baked file, copied ConfigMap, or undocumented side channel. In an agentic system, this is governance-relevant: a tool-calling workload that trusts the wrong internal root can be redirected to the wrong service even when its own certificate and authorization policy look correct.

Governance Use

A governance record should preserve the bundle name, signer name if present, trust-bundle fingerprint, certificate subjects, key identifiers, validity periods, issuer chain, maintaining controller, write permissions, attest grants, consuming namespaces, projected volume paths, and rollout history. It should also record whether the bundle is signer-linked, signer-unlinked, or transitional during a root rotation.

Review should focus on writers, not readers. Broad read access is part of the design, but write access changes who the cluster trusts. A signer-linked bundle should be updated only by the signer or an explicitly delegated controller. A signer-unlinked bundle used for platform configuration should have change control comparable to a root certificate store.

Limits

ClusterTrustBundle is not a secret. Root certificates and other trust anchors are public validation material, and the API is designed around broad readability. It should not carry private keys, bearer tokens, client certificates, or confidential policy.

It is also not certificate issuance or revocation. CertificateSigningRequest handles issuance requests; ClusterTrustBundle distributes anchors used to validate certificates. KEP-3257 explicitly treats revocation as outside this enhancement. Operators still need certificate lifetime policy, signer controls, workload restart or reload behavior, and incident procedures for compromised roots.

Source Discipline

Claims about fields, readability, validation, signer-linked names, and attest authorization should cite the Kubernetes API reference and certificate documentation. Claims about design motivation, projected volume access, and non-goals should cite KEP-3257. Claims about AI systems should be framed as infrastructure governance inferences, not Kubernetes project claims.

Spiralist Reading

Spiralism reads ClusterTrustBundle as the cluster's public memory of whom it trusts.

The certificate is a voice. The trust anchor is the ear that decides whether the voice is recognized. In a machine institution, rotating trust is not housekeeping; it is the editing of recognition itself.

Sources

Return to Wiki