Add overview for Configuration concept #51899

lmktfy · 2025-08-12T22:27:45Z

The motivation for this PR was to be able to explain KEP-3721: Support for env files. After PR #51415 merged I wanted to also help readers discover that the new support exists.

However, to add that section, I needed a page to have around it. Hence:

this PR
my (intentional) choice of base branch: dev-1.34

Current page, vs preview

netlify · 2025-08-12T22:27:50Z

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

Name	Link
🔨 Latest commit	`d775ae7`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-vnext-staging/deploys/68ae21421182d10008f6a7b2

netlify · 2025-08-12T22:37:53Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`aa8b486`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/68cbbad8a2e5340008050491
😎 Deploy Preview	https://deploy-preview-51899--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

tengqm · 2025-08-21T07:17:46Z

content/en/docs/concepts/configuration/_index.md

 weight: 80
 description: >
-  Resources that Kubernetes provides for configuring Pods.
+  Configuration mechanisms within Kubernetes.


The original text is much clearer than the revised version.

See #51899 (comment) and also #51899 (comment) (feedback on the feedback).

This is still the description I recommend using.

As workload configuration in Kubernetes matures, end users have gone beyond using Kubernetes objects / resources to configure Pods. Including init and sidecar containers, I've also seen external storage mounted via CSI driver/mounted PVs used to configure Pods.
The original description scoped the configuration to Pods but the page includes cluster configuration aspects. Imo, generalizing the description for configuration is more accurate to the page

The intent of this page, as I see it, is to provide end users an overview for configuring their workloads. In many scenarios, for stability or security reasons, an end user is not permitted to configure the cluster. In other words, the cluster configuration topic is for cluster admins. We are not supposed to compile everything into this page simply because a topic is about "configuration".

It is perfectly okay to add a note at the beginning of the page, pointing users to admin-specific topics if that is what they are looking for.

tengqm · 2025-08-21T07:18:54Z

content/en/docs/concepts/configuration/_index.md

+If you wanted to learn about configuring the `kubectl` command line tool,
+read [configure access to multiple clusters](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).


This sentence is irrelevant.

@tengqm, here's the problem:

people search the web, eg https://duckduckgo.com/?q=configure+Kubernetes

however, that tells them how to set up a cluster

they don't want a cluster

they have a cluster

they want to configure cluster access

we don't yet have a guide to that; see Add a task page for setting up kubeconfig #38681 for my rationale

they click around and find the Configuration section

We can signpost them to where they want to be. Signposts aren't for people who know where they are going; they are for the otherwise lost.

tengqm · 2025-08-21T07:20:53Z

content/en/docs/concepts/configuration/_index.md

+
+Secrets are similar to {{< glossary_tooltip text="ConfigMaps" term_id="configmap" >}}
+but are specifically intended to hold confidential data. Read the page about Secrets
+to learn about the benefits (and limitations) around information security and Secrets.


Either remove the last sentence, or provide a link.

tengqm · 2025-08-21T07:22:34Z

content/en/docs/concepts/configuration/_index.md

+configuration or security keys or other information that your containers must
+use, and that shouldn't be stored in container images.
+
+### Sidecar container helper {#config-helper-sidecar}


This is a misunderstanding of sidecar.
What you want to explain here is the ImageVolume feature.

I think I understand sidecars. In fact, given I'm employed to be a Kubernetes expert, I am confident I understand sidecars.

We could add a mention of ImageVolume, but a sidecar configuration helper is absolutely a thing, and it provides benefits that image volume does not (notable: real time updating).

Sidecar's are meant to better the main application container and providing configuration is one way to better app containers.
The 2015 blog from Brendan Burns that talked about sidecars describes a sidecar that synchronizes the filesystem with git and git is often used to store app configuration

tengqm · 2025-08-21T07:23:19Z

content/en/docs/concepts/configuration/_index.md

+#### Configuration via the filesystem {#init-container-shared-volume}
+
+With this option, the init container fetches configuration and writes the configuration to
+a file, or several files, within a Pod-local volume.


This doesn't have to be Pod-local.

tengqm · 2025-08-21T07:24:45Z

content/en/docs/concepts/configuration/_index.md

+* [Cluster Administration](/docs/concepts/cluster-administration/)
+  * [API server authentication configuration](/docs/reference/access-authn-authz/authentication/#using-authentication-configuration)
+  * [API server authorization configuration](/docs/reference/access-authn-authz/authorization/#using-configuration-file-for-authorization)
+  * [Configure Certificate Rotation for the Kubelet](/docs/tasks/tls/certificate-rotation/)
+  * [Reconfiguring a `kubeadm` Cluster](/docs/tasks/administer-cluster/kubeadm/kubeadm-reconfigure/)
+  * [Configuring a CGroup Driver](/docs/tasks/administer-cluster/kubeadm/configure-cgroup-driver/)
+  * [Create Static Pods](/docs/tasks/configure-pod-container/static-pod/), relevant to
+    control plane configuration
+  * [Configure the Aggregation Layer](/docs/tasks/extend-kubernetes/configure-aggregation-layer/)


These have nothing to do with the so said "configuration".

I can't find a good way to resolve our difference on this one. For me, the link between "configuration" and "API server authorization configuration" is straightforward to make.

divya-mohan0209 · 2025-08-21T10:49:52Z

@tengqm Thank you for taking time out time to provide your feedback on the PR. Gentle reminder to please consider providing actionable items in a neutral voice since asynchronous & text-based feedback can be misconstrued even if you don't intend for them to be that way.

tengqm · 2025-08-21T12:41:36Z

@tengqm Thank you for taking time out time to provide your feedback on the PR. Gentle reminder to please consider providing actionable items in a neutral voice since asynchronous & text-based feedback can be misconstrued even if you don't intend for them to be that way.

Which comments are you referring to, @divya-mohan0209 ? I just rechecked all feedbacks I provided and I failed to see anything inappropriate.

divya-mohan0209 · 2025-08-21T13:01:41Z

@tengqm The feedback wasn't inappropriate, some of it wasn't actionable/constructive for the submitter.

As aforementioned, that mustn't have been your intention and we fully understand that. However, it'd be valuable to state what is expected of the submitter while reviewing their PR instead of being dismissive and/or providing commentary like you've done here, here, and here. Trust that clarifies what you're looking for?

tengqm · 2025-08-21T13:26:12Z

@tengqm The feedback wasn't inappropriate, some of it wasn't actionable/constructive for the submitter.

As aforementioned, that mustn't have been your intention and we fully understand that. However, it'd be valuable to state what is expected of the submitter while reviewing their PR instead of being dismissive and/or providing commentary like you've done here, here, and here. Trust that clarifies what you're looking for?

For new text added in a PR, when we say they are irrelevant, it is pretty clear that my suggestion is to remove them or add them somewhere else. Right?

For text that are technically inaccurate, for example, "This doesn't have to be Pod-local.".
I mean that an init container doesn't have to share data with an app container using Pod-local volumes. Data can be saved by an init container to any place that the app container can access. For example, the shared storage can be a CSI drive, a GIT repo, a HTTP server etc. Do you mean I have to write a verbose version for the submitter to understand?

As for these have nothing to do with the so said "configuration". It is clear that this page is about ways to provide configuration data for a cloud native application. Most people working in this domain are aware of the 12-factors principle. The submitter is making the page confusing to readers. Configurations related to applications (designed for application owners) are mixed to configurations related to the cluster (designed for cluster admins). Am I making it clear now?

lmktfy · 2025-08-26T20:58:50Z

I had a look at https://kubernetes.io/docs/concepts/configuration/

Here are the topics:

Although three of the pages are definitely about app configuration, they're actually in the minority.

We should fix that, though not in this PR. Until we do, the way I've written it is better (I assert) than to say that the content in this section is purely about how to configure your app.

lmktfy · 2025-08-26T21:02:11Z

I'm confident that making this change makes the docs better.

Here's a thought experiment: if this were merged, would we accept a PR to delete that content, leaving this (the content at time of writing)?

lmktfy · 2025-08-26T21:03:59Z

For text that are technically inaccurate, for example, "This doesn't have to be Pod-local.". I mean that an init container doesn't have to share data with an app container using Pod-local volumes. Data can be saved by an init container to any place that the app container can access. For example, the shared storage can be a CSI drive, a GIT repo, a HTTP server etc. Do you mean I have to write a verbose version for the submitter to understand?

For this specific aspect, I can push an update (and have done).

reylejano · 2025-08-28T19:11:52Z

@lmktfy , with dev-1.34 branch merged to main yesterday, can you change the target of this PR to main

lmktfy · 2025-08-28T22:47:25Z

/remove-area blog
/remove-area release-eng
/remove-language ko pl pt ru zh

lmktfy · 2025-08-28T22:55:33Z

@lmktfy , with dev-1.34 branch merged to main yesterday, can you change the target of this PR to main

done

k8s-ci-robot · 2025-09-01T17:27:21Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign katcosgrove for approval. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

content/en/docs/OWNERS

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

jayeshmahajan · 2025-09-07T00:34:29Z

/remove-language hi

lmktfy · 2025-09-07T07:24:01Z

/remove-label language/bn
/remove-label language/hi
/remove-label language/id
/remove-label language/ja
/remove-area localization

k8s-ci-robot · 2025-09-07T07:24:04Z

@lmktfy: The label(s) /remove-label language/bn , /remove-label language/hi , /remove-label language/id , /remove-label language/ja cannot be applied. These labels are supported: api-review, tide/merge-method-merge, tide/merge-method-rebase, tide/merge-method-squash, team/katacoda, refactor, ci-short, ci-extended, ci-full. Is this label configured under labels -> additional_labels or labels -> restricted_labels in plugin.yaml?

In response to this:

/remove-label language/bn
/remove-label language/hi
/remove-label language/id
/remove-label language/ja
/remove-area localization

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

lmktfy · 2025-09-09T19:31:02Z

/remove-language bn
/remove-language id
/remove-language ja

lmktfy · 2025-09-09T19:31:18Z

/remove-sig release

content/en/docs/concepts/configuration/_index.md

Co-authored-by: Rey Lejano <[email protected]>

k8s-ci-robot added this to the 1.34 milestone Aug 12, 2025

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. language/en Issues or PRs related to English language labels Aug 12, 2025

k8s-ci-robot requested review from katcosgrove and reylejano August 12, 2025 22:27

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Aug 12, 2025

lmktfy force-pushed the 20250812_add_configuration_overview branch from 7110784 to 08a3c33 Compare August 14, 2025 18:05

lmktfy mentioned this pull request Aug 19, 2025

Add FileEnvSource and FileKeySelector to add environment generated on the fly kubernetes/enhancements#3721

Open

10 tasks

tengqm reviewed Aug 21, 2025

View reviewed changes

lmktfy force-pushed the 20250812_add_configuration_overview branch from 08a3c33 to d775ae7 Compare August 26, 2025 21:04

lmktfy force-pushed the 20250812_add_configuration_overview branch from d775ae7 to ea75080 Compare August 28, 2025 22:46

lmktfy force-pushed the 20250812_add_configuration_overview branch from ea75080 to bb0d273 Compare September 1, 2025 17:27

lmktfy force-pushed the 20250812_add_configuration_overview branch from bb0d273 to 646df8f Compare September 1, 2025 17:29

k8s-ci-robot removed the language/hi Issues or PRs related to Hindi language label Sep 7, 2025

k8s-ci-robot removed the area/localization General issues or PRs related to localization label Sep 7, 2025

k8s-ci-robot removed language/bn Issues or PRs related to Bengali language language/id Issues or PRs related to Indonesian language language/ja Issues or PRs related to Japanese language labels Sep 9, 2025

k8s-ci-robot removed the sig/release Categorizes an issue or PR as relevant to SIG Release. label Sep 9, 2025

lmktfy requested a review from tengqm September 9, 2025 19:31

lmktfy removed this from the 1.34 milestone Sep 17, 2025

Add overview page for Configuration

ca951d7

lmktfy force-pushed the 20250812_add_configuration_overview branch from 646df8f to ca951d7 Compare September 17, 2025 20:40

reylejano reviewed Sep 17, 2025

View reviewed changes

content/en/docs/concepts/configuration/_index.md Outdated Show resolved Hide resolved

reylejano reviewed Sep 17, 2025

View reviewed changes

content/en/docs/concepts/configuration/_index.md Outdated Show resolved Hide resolved

Tweak wording

aa8b486

Co-authored-by: Rey Lejano <[email protected]>

		If you wanted to learn about configuring the `kubectl` command line tool,
		read [configure access to multiple clusters](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).

Add overview for Configuration concept #51899

Are you sure you want to change the base?

Add overview for Configuration concept #51899

Conversation

lmktfy commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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

Uh oh!

netlify bot commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reylejano Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

divya-mohan0209 commented Aug 21, 2025

Uh oh!

tengqm commented Aug 21, 2025

Uh oh!

divya-mohan0209 commented Aug 21, 2025

Uh oh!

tengqm commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lmktfy commented Aug 26, 2025

Uh oh!

lmktfy commented Aug 26, 2025

Uh oh!

lmktfy commented Aug 26, 2025

Uh oh!

reylejano commented Aug 28, 2025

Uh oh!

lmktfy commented Aug 28, 2025

Uh oh!

lmktfy commented Aug 28, 2025

Uh oh!

k8s-ci-robot commented Sep 1, 2025

Uh oh!

jayeshmahajan commented Sep 7, 2025

Uh oh!

lmktfy commented Sep 7, 2025

Uh oh!

k8s-ci-robot commented Sep 7, 2025

Uh oh!

lmktfy commented Sep 9, 2025

Uh oh!

lmktfy commented Sep 9, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmktfy commented Aug 12, 2025 •

edited

Loading

netlify bot commented Aug 12, 2025 •

edited

Loading

netlify bot commented Aug 12, 2025 •

edited

Loading

reylejano Sep 17, 2025 •

edited

Loading

tengqm commented Aug 21, 2025 •

edited

Loading