Merge pull request #43600 from ahmedtd/ctb-projection

ClusterTrustBundles: document projected volumes

content/en/docs/concepts/storage/projected-volumes.md

@@ -24,6 +24,7 @@ Currently, the following types of volume sources can be projected:
 * [`downwardAPI`](/docs/concepts/storage/volumes/#downwardapi)
 * [`configMap`](/docs/concepts/storage/volumes/#configmap)
 * [`serviceAccountToken`](#serviceaccounttoken)
+* [`clusterTrustBundle`](#clustertrustbundle)
 
 All sources are required to be in the same namespace as the Pod. For more details,
 see the [all-in-one volume](https://git.k8s.io/design-proposals-archive/node/all-in-one-volume.md) design document.
@@ -70,6 +71,31 @@ A container using a projected volume source as a [`subPath`](/docs/concepts/stor
 volume mount will not receive updates for those volume sources.
 {{< /note >}}
 
+## clusterTrustBundle projected volumes {#clustertrustbundle}
+
+{{<feature-state for_k8s_version="v1.29" state="alpha" >}}
+
+{{< note >}}
+To use this feature in Kubernetes {{< skew currentVersion >}}, you must enable support for ClusterTrustBundle objects with the `ClusterTrustBundle` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) and `--runtime-config=certificates.k8s.io/v1alpha1/clustertrustbundles=true` kube-apiserver flag, then enable the `ClusterTrustBundleProjection` feature gate.
+{{< /note >}}
+
+The `clusterTrustBundle` projected volume source injects the contents of one or more [ClusterTrustBundle](/docs/reference/access-authn-authz/certificate-signing-requests#cluster-trust-bundles) objects as an automatically-updating file in the container filesystem.
+
+ClusterTrustBundles can be selected either by [name](/docs/reference/access-authn-authz/certificate-signing-requests#ctb-signer-unlinked) or by [signer name](/docs/reference/access-authn-authz/certificate-signing-requests#ctb-signer-linked).
+
+To select by name, use the `name` field to designate a single ClusterTrustBundle object.
+
+To select by signer name, use the `signerName` field (and optionally the
+`labelSelector` field) to designate a set of ClusterTrustBundle objects that use
+the given signer name. If `labelSelector` is not present, then all
+ClusterTrustBundles for that signer are selected.
+
+The kubelet deduplicates the certificates in the selected ClusterTrustBundle objects, normalizes the PEM representations (discarding comments and headers), reorders the certificates, and writes them into the file named by `path`. As the set of selected ClusterTrustBundles or their content changes, kubelet keeps the file up-to-date.
+
+By default, the kubelet will prevent the pod from starting if the named ClusterTrustBundle is not found, or if `signerName` / `labelSelector` do not match any ClusterTrustBundles.  If this behavior is not what you want, then set the `optional` field to `true`, and the pod will start up with an empty file at `path`.
+
+{{% code_sample file="pods/storage/projected-clustertrustbundle.yaml" %}}
+
 ## SecurityContext interactions
 
 The [proposal](https://git.k8s.io/enhancements/keps/sig-storage/2451-service-account-token-volumes#proposal) for file permission handling in projected service account volume enhancement introduced the projected files having the correct owner permissions set.

content/en/docs/reference/access-authn-authz/certificate-signing-requests.md

@@ -371,7 +371,7 @@ you like. If you want to add a note for human consumption, use the
 {{< feature-state for_k8s_version="v1.27" state="alpha" >}}
 
 {{< note >}}
-In Kubernetes {{< skew currentVersion >}}, you must enable the `ClusterTrustBundles`
+In Kubernetes {{< skew currentVersion >}}, you must enable the `ClusterTrustBundle`
 [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
 _and_ the `certificates.k8s.io/v1alpha1`
 {{< glossary_tooltip text="API group" term_id="api-group" >}} in order to use
@@ -472,6 +472,12 @@ such as role-based access control.
 To distinguish them from signer-linked ClusterTrustBundles, the names of
 signer-unlinked ClusterTrustBundles **must not** contain a colon (`:`).
 
+### Accessing ClusterTrustBundles from pods {#ctb-projection}
+
+{{<feature-state for_k8s_version="v1.29" state="alpha" >}}
+
+The contents of ClusterTrustBundles can be injected into the container filesystem, similar to ConfigMaps and Secrets.  See the [clusterTrustBundle projected volume source](/docs/concepts/storage/projected-volumes#clustertrustbundle) for more details.
+
 <!-- TODO this should become a task page -->
 ## How to issue a certificate for a user {#normal-user}
 

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -82,6 +82,7 @@ For a reference to old feature gates that are removed, please refer to
 | `CloudDualStackNodeIPs` | `false` | Alpha | 1.27 | 1.28 |
 | `CloudDualStackNodeIPs` | `true` | Beta | 1.29 | |
 | `ClusterTrustBundle` | false | Alpha | 1.27 | |
+| `ClusterTrustBundleProjection` | `false` | Alpha | 1.29 | |
 | `ComponentSLIs` | `false` | Alpha | 1.26 | 1.26 |
 | `ComponentSLIs` | `true` | Beta | 1.27 | |
 | `ConsistentListFromCache` | `false` | Alpha | 1.28 | |
@@ -444,7 +445,8 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `CloudDualStackNodeIPs`: Enables dual-stack `kubelet --node-ip` with external cloud providers.
   See [Configure IPv4/IPv6 dual-stack](/docs/concepts/services-networking/dual-stack/#configure-ipv4-ipv6-dual-stack)
   for more details.
-- `ClusterTrustBundle`: Enable ClusterTrustBundle objects and kubelet integration.
+- `ClusterTrustBundle`: Enable ClusterTrustBundle objects.
+- `ClusterTrustBundleProjection`: [`clusterTrustBundle` projected volume sources](/docs/concepts/storage/projected-volumes#clustertrustbundle).
 - `ComponentSLIs`: Enable the `/metrics/slis` endpoint on Kubernetes components like
   kubelet, kube-scheduler, kube-proxy, kube-controller-manager, cloud-controller-manager
   allowing you to scrape health check metrics.

content/en/examples/pods/storage/projected-clustertrustbundle.yaml

@@ -0,0 +1,28 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: sa-ctb-name-test
+spec:
+  containers:
+  - name: container-test
+    image: busybox
+    command: ["sleep", "3600"]
+    volumeMounts:
+    - name: token-vol
+      mountPath: "/root-certificates"
+      readOnly: true
+  serviceAccountName: default
+  volumes:
+  - name: root-certificates-vol
+    projected:
+      sources:
+      - clusterTrustBundle:
+          name: example
+          path: example-roots.pem
+      - clusterTrustBundle:
+          signerName: "example.com/mysigner"
+          labelSelector:
+            matchLabels:
+              version: live
+          path: mysigner-roots.pem
+          optional: true