ClusterTrustBundles: document projected volumes #43600

ahmedtd · 2023-10-20T03:26:36Z

ClusterTrustBundle projected volume sources are slated to land in 1.29. Drop a ~~placeholder~~ section in the existing ClusterTrustBundle documentation to document it.

Enhancements Issue: kubernetes/enhancements#3257
Implementation PR: kubernetes/kubernetes#113374

netlify · 2023-10-20T03:26:42Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	`6dd3091`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/655ce772557ee800084bb5e3

sftim · 2023-10-20T12:03:34Z

/sig security
/sig auth

/retitle [WIP] ClusterTrustBundles: document projected volumes

sftim

Thanks

Be sure to update https://k8s.io/docs/concepts/storage/projected-volumes/ as well

katcosgrove · 2023-10-30T10:53:45Z

Hi, @ahmedtd! v1.29 Docs Lead here. Please take a look at Documenting for a release - PR Ready for Review to get your PR ready for review before Tuesday 14th November 2023. Thank you!

ahmedtd · 2023-11-12T04:13:46Z

@sftim @enj This is ready for review.

liggitt

looks good, just a few nits / suggestions

also add rows in https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/ for ClusterTrustBundle and ClusterTrustBundleProjection gates

liggitt · 2023-11-14T13:13:55Z

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

+
+{{< note >}}
+In Kubernetes {{< skew currentVersion >}}, you must enable the  `ClusterTrustBundle` and `ClusterTrustBundleProjection`
+[feature gates](/docs/reference/command-line-tools-reference/feature-gates/) to use this feature.


and API, right (with --runtime-config=certificates.k8s.io/v1alpha1/clustertrustbundles=true)?

liggitt · 2023-11-14T13:14:47Z

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

+
+To select by name, use the `name` field to designate a single ClusterTrustBundle object.
+
+To select by signer name, use the `signerName` and `labelSelector` fields to


Suggested change

To select by signer name, use the `signerName` and `labelSelector` fields to

To select by signer name, use the `signerName` field (and optionally the `labelSelector` field) to

liggitt · 2023-11-14T13:16:55Z

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

+If `labelSelector` is not present, then all ClusterTrustBundles for that signer
+are selected.
+
+In both cases, Kubelet will deduplicate all of the certificates from the selected ClusterTrustBundle objects, normalize the PEM representations (discarding comments and headers), and shuffle the order of the certificates before writing them into the file named by `path`.  As the set of selected ClusterTrustBundles, or their content, changes, Kubelet will keep the file up-to-date.


Suggested change

In both cases, Kubelet will deduplicate all of the certificates from the selected ClusterTrustBundle objects, normalize the PEM representations (discarding comments and headers), and shuffle the order of the certificates before writing them into the file named by `path`. As the set of selected ClusterTrustBundles, or their content, changes, Kubelet will keep the file up-to-date.

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.

liggitt · 2023-11-14T13:17:49Z

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

+spec:
+  containers:
+  - name: container-test
+    image: busybox:1.28


nit: why the 1.28 tag?

Copied this from the example next to it. Removed.

liggitt · 2023-11-14T13:18:32Z

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

+          name: foo
+          path: foo-roots.pem


nit: use something like example instead of foo?

liggitt · 2023-11-14T14:07:12Z

/assign

ahmedtd · 2023-11-17T04:05:55Z

also add rows in https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/ for ClusterTrustBundle and ClusterTrustBundleProjection gates

Done.

enj · 2023-11-17T15:21:15Z

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

Add docs for the projected feature gate in the List of feature gates section.

enj · 2023-11-17T15:25:18Z

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

@@ -71,6 +71,8 @@ For a reference to old feature gates that are removed, please refer to
 | `AnyVolumeDataSource` | `false` | Alpha | 1.18 | 1.23 |
 | `AnyVolumeDataSource` | `true` | Beta | 1.24 | |
 | `AppArmor` | `true` | Beta | 1.4 | |
+| `ClusterTrustBundle` | `false` | Alpha | 1.28 | |


This is already in this file (see below on line 89).

This is the key outstanding feedback blocking a merge, I think.

katcosgrove · 2023-11-20T16:36:15Z

Hi, @ahmedtd! Kubernetes v1.29 Docs Lead here. Just a reminder that the deadline to have this PR reviewed and merged is Tuesday, 28 November. Let me know if you need any help!

CCing KEP owners: @liggitt @enj @mikedanese

sftim · 2023-11-20T16:58:23Z

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

+
+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 desired, then set the `optional` field to `true`, and the pod will start up with an empty file at `path`.


(a nit)

Suggested change

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 desired, then set the `optional` field to `true`, and the pod will start up with an empty file at `path`.

By default, the kubelet prevents 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`.

sftim · 2023-11-20T16:59:28Z

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

@@ -71,6 +71,8 @@ For a reference to old feature gates that are removed, please refer to
 | `AnyVolumeDataSource` | `false` | Alpha | 1.18 | 1.23 |
 | `AnyVolumeDataSource` | `true` | Beta | 1.24 | |
 | `AppArmor` | `true` | Beta | 1.4 | |
+| `ClusterTrustBundle` | `false` | Alpha | 1.28 | |
+| `ClusterTrustBundleProjection` | `false` | Alpha | 1.29 | |


Please preserve the existing collation order (#41793 may help us automate sorting, but that has not yet landed).

enj · 2023-11-21T14:04:06Z

/lgtm

k8s-ci-robot · 2023-11-21T14:04:19Z

LGTM label has been added.

Git tree hash: 627313af259e477714afa4b93392d4a52c4ba6b6

sftim

Thanks

/approve

sftim · 2023-11-21T16:09:57Z

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

+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 objects as an automatically-updating file in the container filesystem.


(nit / good to fix for beta)
That first mention of ClusterTrustBundle could link to https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/#cluster-trust-bundles

sftim · 2023-11-21T16:14:40Z

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

@@ -441,7 +442,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`: Enable kubelet ClusterTrustBundle projected volume sources.


(nit)

Suggested change

- `ClusterTrustBundleProjection`: Enable kubelet ClusterTrustBundle projected volume sources.

- `ClusterTrustBundleProjection`: Enable

[`clusterTrustBundle` projected volume sources](/docs/concepts/storage/projected-volumes#clustertrustbundle).

k8s-ci-robot · 2023-11-21T16:15:18Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: sftim

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [sftim]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

sftim · 2023-11-21T16:17:02Z

Netlify, our static site rendering and serving service, has got into a pickle @ahmedtd

If you edit the commit (can be a no-op other than, eg, a different commit date) and force-push, that might help unbreak things.

ahmedtd · 2023-11-21T20:58:42Z

OK, looks like netlify is succeeding now.

enj · 2023-11-21T23:04:30Z

/lgtm

k8s-ci-robot · 2023-11-21T23:04:37Z

LGTM label has been added.

Git tree hash: 6868d9dece5b1b2bef78b68d130d1dbf4a8e5c2a

k8s-ci-robot added this to the 1.29 milestone Oct 20, 2023

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Oct 20, 2023

k8s-ci-robot requested review from mikedanese and munnerz October 20, 2023 03:26

k8s-ci-robot added language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Oct 20, 2023

ahmedtd mentioned this pull request Oct 20, 2023

ClusterTrustBundles (previously Trust Anchor Sets) kubernetes/enhancements#3257

Open

14 tasks

k8s-ci-robot changed the title ~~ClusterTrustBundles: Document projected volumes~~ [WIP] ClusterTrustBundles: document projected volumes Oct 20, 2023

k8s-ci-robot added sig/security Categorizes an issue or PR as relevant to SIG Security. sig/auth Categorizes an issue or PR as relevant to SIG Auth. do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. labels Oct 20, 2023

sftim reviewed Oct 20, 2023

View reviewed changes

ahmedtd force-pushed the ctb-projection branch from e6bcd33 to 48db373 Compare November 12, 2023 04:11

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Nov 12, 2023

ahmedtd changed the title ~~[WIP] ClusterTrustBundles: document projected volumes~~ ClusterTrustBundles: document projected volumes Nov 12, 2023

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 12, 2023

ahmedtd force-pushed the ctb-projection branch from 48db373 to 9e65d6b Compare November 12, 2023 04:12

liggitt reviewed Nov 14, 2023

View reviewed changes

k8s-ci-robot assigned liggitt Nov 14, 2023

ahmedtd force-pushed the ctb-projection branch from 9e65d6b to 130f234 Compare November 17, 2023 04:05

enj suggested changes Nov 17, 2023

View reviewed changes

sftim reviewed Nov 20, 2023

View reviewed changes

ahmedtd force-pushed the ctb-projection branch from 130f234 to 1779874 Compare November 21, 2023 03:44

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 21, 2023

ahmedtd force-pushed the ctb-projection branch from 1779874 to 774e1fe Compare November 21, 2023 03:46

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 21, 2023

k8s-ci-robot assigned enj Nov 21, 2023

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 21, 2023

sftim reviewed Nov 21, 2023

View reviewed changes

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 21, 2023

ClusterTrustBundles: Document projected volumes

6dd3091

ahmedtd force-pushed the ctb-projection branch from 774e1fe to 6dd3091 Compare November 21, 2023 17:22

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 21, 2023

k8s-ci-robot requested review from enj and liggitt November 21, 2023 17:22

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 21, 2023

k8s-ci-robot merged commit 99df3a3 into kubernetes:dev-1.29 Nov 21, 2023
6 checks passed


		To select by name, use the `name` field to designate a single ClusterTrustBundle object.

		To select by signer name, use the `signerName` and `labelSelector` fields to

	In both cases, Kubelet will deduplicate all of the certificates from the selected ClusterTrustBundle objects, normalize the PEM representations (discarding comments and headers), and shuffle the order of the certificates before writing them into the file named by `path`. As the set of selected ClusterTrustBundles, or their content, changes, Kubelet will keep the file up-to-date.
	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.


		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 desired, then set the `optional` field to `true`, and the pod will start up with an empty file at `path`.

	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 desired, then set the `optional` field to `true`, and the pod will start up with an empty file at `path`.
	By default, the kubelet prevents 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`.

	- `ClusterTrustBundleProjection`: Enable kubelet ClusterTrustBundle projected volume sources.
	- `ClusterTrustBundleProjection`: Enable
	[`clusterTrustBundle` projected volume sources](/docs/concepts/storage/projected-volumes#clustertrustbundle).

ClusterTrustBundles: document projected volumes #43600

ClusterTrustBundles: document projected volumes #43600

Conversation

ahmedtd commented Oct 20, 2023 • edited by sftim Loading

netlify bot commented Oct 20, 2023 • edited Loading

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

sftim commented Oct 20, 2023

sftim left a comment

Choose a reason for hiding this comment

katcosgrove commented Oct 30, 2023

ahmedtd commented Nov 12, 2023

liggitt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liggitt commented Nov 14, 2023

ahmedtd commented Nov 17, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

katcosgrove commented Nov 20, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

enj commented Nov 21, 2023

k8s-ci-robot commented Nov 21, 2023

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

k8s-ci-robot commented Nov 21, 2023

sftim commented Nov 21, 2023

ahmedtd commented Nov 21, 2023

enj commented Nov 21, 2023

k8s-ci-robot commented Nov 21, 2023

ahmedtd commented Oct 20, 2023 •

edited by sftim

Loading

netlify bot commented Oct 20, 2023 •

edited

Loading