feat: Create Advanced Pod Configuration page and restructure main Pod documentation #51519

Caesarsage · 2025-07-05T16:33:01Z

This PR implements the feature request from issue #51423 to create a dedicated Advanced Pod Configuration page and restructure the main Pod documentation for better user experience.

Changes:
Creates /docs/concepts/workloads/pods/advanced-pod-config/ with comprehensive coverage of:

Priority Classes
Runtime Classes
Advanced Security Context
Node Selection strategies
Pod Overhead

Simplifies main Pod page to focus on basic concepts
Adds cross-references between basic and advanced topics
Positions advanced page last in navigation (weight: 180)

Related Issues:

Addresses #51423: "Pod Restructuring: Create Advanced Pod Configuration page"
Supports broader Pod documentation restructuring effort (#38867)

Closes: #51423

… Configuration Updated the Pods documentation to provide clearer examples of basic and advanced security context configurations. Added a new page for Advanced Pod Configuration covering priority classes, runtime classes, and node selection strategies, along with detailed YAML examples for each topic. This improves the clarity and usability of security settings in Kubernetes Pods.

…ate-pod-advance-config-page

Caesarsage · 2025-07-05T16:35:19Z

Hello @lmktfy

Kindly check this out on the pod restructuring issue

netlify · 2025-07-05T16:43:26Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`0a3ab87`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/68d092890d12130008f310f6
😎 Deploy Preview	https://deploy-preview-51519--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.

lmktfy

@Caesarsage thank you for working on this.

What you've done is a great first step, but it's not aligned enoug to our style guide for me to accept it as is.

Now, I've added a lot of suggestions. You don't have to accept any of them, but we do need the page we merge to mostly align with the style guide. All new pages should follow that style guide reasonably closely.

Would you be willing to revise this based on feedback?

lmktfy · 2025-07-30T22:45:08Z

content/en/docs/concepts/workloads/pods/_index.md

-{{< /caution >}}
+granular control over what a Pod or individual containers can do.
+
+For basic security configuration, you can set simple security contexts:


I would specifically recommend meeting the Baseline Pod security standard + running as non-root.

lmktfy · 2025-07-30T22:46:12Z

content/en/docs/concepts/workloads/pods/_index.md

+    command: ["sh", "-c", "sleep 1h"]
+```
+
+For advanced security context configuration including capabilities, seccomp profiles, and detailed security options, see [Advanced Pod Configuration](/docs/concepts/workloads/pods/advanced-pod-config/#advanced-security-context-configuration).


Let's link to the security concepts section instead.

lmktfy · 2025-07-30T22:49:48Z

content/en/docs/concepts/workloads/pods/_index.md

  object definition describes the object in detail.
 * [The Distributed System Toolkit: Patterns for Composite Containers](/blog/2015/06/the-distributed-system-toolkit-patterns/) explains common layouts for Pods with more than one container.
 * Read about [Pod topology spread constraints](/docs/concepts/scheduling-eviction/topology-spread-constraints/)
+* Explore [Advanced Pod Configuration](/docs/concepts/workloads/pods/advanced-pod-config/) for priority classes, runtime classes, and detailed node selection strategies.


Suggested change

* Explore [Advanced Pod Configuration](/docs/concepts/workloads/pods/advanced-pod-config/) for priority classes, runtime classes, and detailed node selection strategies.

* Read [Advanced Pod Configuration](/docs/concepts/workloads/pods/advanced-pod-config/) to learn the topic in detail.

That page covers aspects of Pod configuration beyond the essentials, including:

* PriorityClasses

* RuntimeClasses

* advanced ways to configure _scheduling_: the way that Kubernetes decides which node a Pod should run on.

lmktfy · 2025-07-30T22:50:55Z

content/en/docs/concepts/workloads/pods/_index.md

 * Learn about the [lifecycle of a Pod](/docs/concepts/workloads/pods/pod-lifecycle/).
-* Learn about [RuntimeClass](/docs/concepts/containers/runtime-class/) and how you can use it to
-  configure different Pods with different container runtime configurations.
 * Read about [PodDisruptionBudget](/docs/concepts/workloads/pods/disruptions/)


I think we should mention this later in the list than the first mention of PriorityClass.

lmktfy · 2025-07-30T22:51:19Z

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

+
+<!-- body -->
+
+## Priority Classes


Suggested change

## Priority Classes

## PriorityClasses

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

lmktfy · 2025-07-30T23:18:39Z

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

+
+Kubernetes provides several mechanisms to control which nodes your Pods are scheduled on.
+
+### Node Selectors


nit: should be sentence case

lmktfy · 2025-07-30T23:19:19Z

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

+    image: nginx
+```
+
+For more information, see [Runtime Class](/docs/concepts/containers/runtime-class/).


Suggested change

For more information, see [Runtime Class](/docs/concepts/containers/runtime-class/).

For more information, see the [RuntimeClass](/docs/concepts/containers/runtime-class/) documentation.

lmktfy · 2025-07-30T23:24:30Z

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

+
+<!-- overview -->
+
+This page covers advanced Pod configuration topics including priority classes, runtime classes, detailed security context configuration, and node selection strategies.


If you make the other changes I suggest, then this would work well:

This page covers advanced Pod configuration topics including [PriorityClasses]{#priorityclasses}, [RuntimeClasses]{#runtimeclasses}, [security context](#security-context) within Pods, and introduces aspects of [scheduling](/docs/concepts/scheduling-eviction/#scheduling).

lmktfy · 2025-07-30T23:27:27Z

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

+
+## Priority Classes
+
+Priority classes allow you to set the importance of Pods relative to other Pods. When a Pod cannot be scheduled, the scheduler tries to preempt (evict) lower priority Pods to make scheduling of the higher priority Pod possible.


Suggested change

Priority classes allow you to set the importance of Pods relative to other Pods. When a Pod cannot be scheduled, the scheduler tries to preempt (evict) lower priority Pods to make scheduling of the higher priority Pod possible.

_PriorityClasses_ allow you to set the importance of Pods relative to other Pods.

If you assign a priority class to a Pod, Kubernetes sets the `.spec.priority` field for that Pod

based on the PriorityClass you specified (you cannot set `.spec.priority` directly).

If or when a Pod cannot be scheduled, and the problem is due to a lack of resources, the {{< glossary_tooltip term_id="kube-scheduler" text="kube-scheduler" >}}

tries to {{< glossary_tooltip text="preempt" term_id="preemption" >}} lower priority

Pods, in order to make scheduling of the higher priority Pod possible.

Caesarsage · 2025-07-30T23:35:57Z

@Caesarsage thank you for working on this.

What you've done is a great first step, but it's not aligned enoug to our style guide for me to accept it as is.

Now, I've added a lot of suggestions. You don't have to accept any of them, but we do need the page we merge to mostly align with the style guide. All new pages should follow that style guide reasonably closely.

Would you be willing to revise this based on feedback?

Thanks for the feedback. Yeah, i will revise base on the feedback and also take another look at the style guide @lmktfy

…ng clarity on priority classes, runtime classes, and security contexts.

Caesarsage · 2025-08-09T13:53:05Z

@lmktfy Thank you for your thorough reviews and detailed feedback. I have refined the pages based on your suggestions and aligned them with the Kubernetes style guide.

lmktfy

/lgtm

I have a few suggestions, but they are not so important that we need to wait for them to get fixed.

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

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

+* Read about [Pod Priority and Preemption](/docs/concepts/scheduling-eviction/pod-priority-preemption/)
+* Read about [RuntimeClasses](/docs/concepts/containers/runtime-class/)
+* Explore [Configure a Security Context for a Pod or Container](/docs/tasks/configure-pod-container/security-context/)
+* [Assign Pods to Nodes](/docs/concepts/scheduling-eviction/assign-pod-node/)


Suggested change

* [Assign Pods to Nodes](/docs/concepts/scheduling-eviction/assign-pod-node/)

* Learn how Kubernetes [assigns Pods to Nodes](/docs/concepts/scheduling-eviction/assign-pod-node/)

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

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

+    command: ["sh", "-c", "sleep 1h"]
+{{< /highlight >}}
+
+### Example Pod {#container-level-security-context}


Suggested change

### Example Pod {#container-level-security-context}

### Container-level security context {#container-level-security-context}

You can specify the security context just for a specific container.

Here's an example:

#### Example Pod {#container-level-security-context-example}

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

content/en/docs/concepts/workloads/pods/advanced-pod-config.md

+
+The `Security context` field in the Pod specification provides granular control over security settings for Pods and containers.
+
+### Example Pod {#pod-level-security-context}


Suggested change

### Example Pod {#pod-level-security-context}

### Pod-wide `securityContext` {#pod-level-security-context}

Some aspects of security apply to the whole Pod; for other aspects,

you might want to set a default, without any container-level overrides.

Here's an example of using `securityContext` at the Pod level:

#### Example Pod {#pod-level-security-context-example}

k8s-ci-robot · 2025-09-07T07:25:22Z

LGTM label has been added.

Git tree hash: 26693177d96a623b7f35abcccaa36e3946c12ed7

lmktfy · 2025-09-07T07:25:42Z

/assign tengqm

per #51519 (comment)

reylejano · 2025-09-18T20:06:03Z

Preview of proposed changes:

reylejano · 2025-09-18T20:11:43Z

content/en/docs/concepts/workloads/pods/_index.md

-security context of the Pod spec. For details and instructions, see
-[Create a Windows HostProcess Pod](/docs/tasks/configure-pod-container/create-hostprocess-pod/).
-{{< /caution >}}
+granular control over what a Pod or individual containers can do.


Since the PR removes the general overview of what general control can be done. Perhaps it's good to link to the new "advanced-pod-config" page. Something like the below suggestion

Suggested change

granular control over what a Pod or individual containers can do.

granular control over what a Pod or individual containers can do. See [Advanced Pod Configuration](/docs/concepts/workloads/pods/advanced-pod-config/) for more details.

Yeah, this is a Good suggestion @reylejano . Thanks.

k8s-ci-robot · 2025-09-22T00:04:27Z

New changes are detected. LGTM label has been removed.

k8s-ci-robot · 2025-09-22T00:04:36Z

[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 ask for approval from lmktfy. 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

Caesarsage · 2025-10-29T10:35:58Z

/assign tengqm

Preview of proposed changes:

https://deploy-preview-51519--kubernetes-io-main-staging.netlify.app/docs/concepts/workloads/pods/
https://deploy-preview-51519--kubernetes-io-main-staging.netlify.app/docs/concepts/workloads/pods/advanced-pod-config/

Caesarsage added 2 commits July 5, 2025 17:24

Merge branch 'main' of https://github.com/Caesarsage/website into cre…

f68625d

…ate-pod-advance-config-page

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 Jul 5, 2025

k8s-ci-robot requested review from dipesh-rawat and katcosgrove July 5, 2025 16:33

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

lmktfy reviewed Jul 30, 2025

View reviewed changes

Refine documentation for Pods and Advanced Pod Configuration, enhanci…

1f3bd8c

…ng clarity on priority classes, runtime classes, and security contexts.

Caesarsage requested a review from lmktfy September 6, 2025 23:16

lmktfy reviewed Sep 7, 2025

View reviewed changes

k8s-ci-robot assigned lmktfy Sep 7, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 7, 2025

k8s-ci-robot assigned tengqm Sep 7, 2025

reylejano reviewed Sep 18, 2025

View reviewed changes

docs: improve page content

0a3ab87

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 22, 2025

k8s-ci-robot requested review from lmktfy and tengqm September 22, 2025 00:04

Caesarsage closed this Oct 29, 2025

Caesarsage reopened this Oct 29, 2025

Caesarsage mentioned this pull request Nov 3, 2025

REQUEST: New membership for caesarsage kubernetes/org#5965

Closed

11 tasks

-* Explore [Advanced Pod Configuration](/docs/concepts/workloads/pods/advanced-pod-config/) for priority classes, runtime classes, and detailed node selection strategies.
+* Read [Advanced Pod Configuration](/docs/concepts/workloads/pods/advanced-pod-config/) to learn the topic in detail.
+  That page covers aspects of Pod configuration beyond the essentials, including:
+  * PriorityClasses
+  * RuntimeClasses
+  * advanced ways to configure _scheduling_: the way that Kubernetes decides which node a Pod should run on.


		Kubernetes provides several mechanisms to control which nodes your Pods are scheduled on.

		### Node Selectors

	For more information, see [Runtime Class](/docs/concepts/containers/runtime-class/).
	For more information, see the [RuntimeClass](/docs/concepts/containers/runtime-class/) documentation.


		<!-- overview -->

		This page covers advanced Pod configuration topics including priority classes, runtime classes, detailed security context configuration, and node selection strategies.


		## Priority Classes

		Priority classes allow you to set the importance of Pods relative to other Pods. When a Pod cannot be scheduled, the scheduler tries to preempt (evict) lower priority Pods to make scheduling of the higher priority Pod possible.

-Priority classes allow you to set the importance of Pods relative to other Pods. When a Pod cannot be scheduled, the scheduler tries to preempt (evict) lower priority Pods to make scheduling of the higher priority Pod possible.
+_PriorityClasses_ allow you to set the importance of Pods relative to other Pods.
+If you assign a priority class to a Pod, Kubernetes sets the `.spec.priority` field for that Pod
+based on the PriorityClass you specified (you cannot set `.spec.priority` directly).
+If or when a Pod cannot be scheduled, and the problem is due to a lack of resources, the {{< glossary_tooltip term_id="kube-scheduler" text="kube-scheduler" >}}
+tries to {{< glossary_tooltip text="preempt" term_id="preemption" >}} lower priority
+Pods, in order to make scheduling of the higher priority Pod possible.

	* [Assign Pods to Nodes](/docs/concepts/scheduling-eviction/assign-pod-node/)
	* Learn how Kubernetes [assigns Pods to Nodes](/docs/concepts/scheduling-eviction/assign-pod-node/)

-### Example Pod {#container-level-security-context}
+### Container-level security context {#container-level-security-context}
+You can specify the security context just for a specific container.
+Here's an example:
+#### Example Pod {#container-level-security-context-example}


		The `Security context` field in the Pod specification provides granular control over security settings for Pods and containers.

		### Example Pod {#pod-level-security-context}

-### Example Pod {#pod-level-security-context}
+### Pod-wide `securityContext` {#pod-level-security-context}
+Some aspects of security apply to the whole Pod; for other aspects,
+you might want to set a default, without any container-level overrides.
+Here's an example of using `securityContext` at the Pod level:
+#### Example Pod {#pod-level-security-context-example}

	granular control over what a Pod or individual containers can do.
	granular control over what a Pod or individual containers can do. See [Advanced Pod Configuration](/docs/concepts/workloads/pods/advanced-pod-config/) for more details.

feat: Create Advanced Pod Configuration page and restructure main Pod documentation #51519

Are you sure you want to change the base?

feat: Create Advanced Pod Configuration page and restructure main Pod documentation #51519

Uh oh!

Conversation

Caesarsage commented Jul 5, 2025

Uh oh!

Caesarsage commented Jul 5, 2025

Uh oh!

netlify bot commented Jul 5, 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!

lmktfy left a comment

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!

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!

Caesarsage commented Jul 30, 2025

Uh oh!

Caesarsage commented Aug 9, 2025

Uh oh!

lmktfy left a comment

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!

k8s-ci-robot commented Sep 7, 2025

Uh oh!

lmktfy commented Sep 7, 2025

Uh oh!

reylejano commented Sep 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Sep 22, 2025

Uh oh!

k8s-ci-robot commented Sep 22, 2025

Uh oh!

Caesarsage commented Oct 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify bot commented Jul 5, 2025 •

edited

Loading