Split Pod concept into a simple introduction and further details

[shirady]

I think this page needs to be separated, today it includes basic information about pods as well as detailed advanced subjects.

https://k8s.io/docs/concepts/workloads/pods/

This page should include:

• What is a Pod?
• Using Pods: Workload resources for managing pods
• Working with Pods: Pod template
• any basic information

... all the rest are detailed advanced subjects, and if someone did not know what is a pod, he will hardly understand those details.

[sftim]

/retitle Split Pod concept into a simple introduction and further details
/language en
/label refactor

/triage accepted
/priority important-longterm

Yes, we should.

Before starting work on this please reply here to outline your approach, and check that SIG Docs is happy with the approach you're considering.

This is an important change to get right.

[devarsh10]

I would like to contribute to this issue. And would like to seperate begineer concepts and advanced concepts of PODs.
Btw, I'm a begineer in Kubernetes but I'm familiar with pod, deployments, sevice and some of its concepts.

Regards,
Devarsh.

[tengqm]

@devarsh10 A beginner's feelings are more useful when differentiating basic concepts from advanced concepts.
Feel free to assign this to yourself.

[devarsh10]

Okay @tengqm.
/assign

[devarsh10]

I have created rough notes of the points you mentioned.
Please let me know if I am going in right direction or not.

K8s_Pod..pdf

[sftim]

I had a look at the PDF.

I'm afraid that it is a bit hard to understand that's in that fil;e, as the language isn't clear (it's not the kind of English that people speak around me).

I'm worried that I can't work out the intent you have here @devash10, and so it's not easy to confirm that you're going in the right direction.

[devarsh10]

Hey all,
I am sorry for the delayed response.
I had created the notes.
I am attaching a PDF. Please consider reviewing it.

Pod Notes

Regards.

[sftim]

What we'd really like is either an editable document (HackMD, Google Doc) where approvers can make suggestions, or a pull request.

I recommend opening an actual pull request.

[devarsh10]

Hello @sftim,
I apologize for the delayed response. I have prepared the Google Doc, and here's the link to it -> Link

My plan is to make changes to the Kubernetes Pod documentation once the Google Doc is approved. Here's the link to the section I'll be editing: https://kubernetes.io/docs/concepts/workloads/pods/

Please let me know if you have any suggestions or if you think this approach could be improved.

[sftim]

/help

[k8s-ci-robot]

@sftim:
This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/help

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.

[sftim]

Help, from any contributor, is welcome.

[mrgiles]

/assign

[mrgiles]

Hello. I have a proposed fix, it doesn't require new content, just reshuffle and distribute what's already in the current index page.

Current: 1 doc: _index.md

_index.md

• Overview
• What is a Pod?
• Using Pods
• Workload resources for managing pods
• Working with Pods
• Pod OS
• Pods and controllers
• Pod templates
• Pod update and replacement
• Resource sharing and communication
• Storage in Pods
• Pod networking
• Pod security settings
• Static Pods
• Pods with multiple containers
• Container probes

Proposed: 3 docs: _index.md, pod-advanced.md, pod-expert.md

_index.md

• Overview
• What is a Pod?
• Using Pods
• Working with Pods
• Pod OS

pod-advanced.md

• Workload resources for managing pods
• Pods and controllers
• Pod templates
• Pod update and replacement
• Resource sharing and communication
• Storage in Pods
• Pod networking
• Pod security settings
• Static Pods

pod-expert.md

• Pods with multiple containers
• Container probes

If there are no objections, I can draft a PR asap. Thanks!

[sftim]

We don't [we try hard not to] split topics by audience expertise @mrgiles. See if you can find a different way to slice up these concepts.

[sftim]

This is important work; however, changes are costly (people bookmark docs), so we like to avoid any need to redo things. That means we invest more effort in getting the reorganization right on the first go.

---

My tips:

• Pod templates are a core part of the concepts people need to learn
• We can link to pages in the containers section, even to pages that don't exist yet
• Tutorials, such as “working with Pods“, could go within https://k8s.io/docs/tutorials/
• Multi container Pods need teaching early on that they can exist, but a separate page could explain the different kinds of multi container Pods
  • Means to share data between containers (volumes? localhost networking?)
    • Could link to “resource sharing and communication”
  • Sidecars
  • Init containers
  • The ambassador pattern
  • Configuration helper sidecars
  • Service meshes
• Similarly, the core page about Pods needs to mention that you can mount storage, but you can split this up
  • Pod-local volumes (emptyDir and friends)
  • Ephemeral external storage
  • Durable external storage
  • Special cases (eg image volumes)

and more!

[mrgiles]

Thanks for the tips, Tim.

My bad, I've got the (wrong) impression that the request in this issue was to split the basic from the advanced content.

If concepts/workloads/pods/_index.md is the landing page for Pod, then it could be rewritten to be more like the Tasks landing page (tasks/_index.md) that just contains a paragraph or two and links to all the other related pages.

In the case of the Pods page, this could have links that lists pod-related content even outside its own section. Then dividing the content further into discrete docs (e.g., per topic) could be streamlined. The main task would then be how to outline this list. I'd go through your tips list to do that sorting.

In a visual search, I've found the following Pod content across the site (I'm sure there's more), part of which could be linked from the landing page:

concepts/workloads/pods/
disruptions.md
downward-api.md
ephemeral-containers.md
_index.md
init-containers.md
pod-lifecycle.md
pod-qos.md
sidecar-containers.md
user-namespaces.md
working-with-pods.md

concepts/scheduling-eviction/
assign-pod-node.md
pod-overhead.md
pod-priority-preemption.md
pod-scheduling-readiness.md

tasks/configure-pod-container/
assign-pods-nodes.md
assign-pods-nodes-using-node-affinity.md
configure-pod-configmap.md
configure-pod-initialization.md
quality-service-pod.md
static-pod.md

tasks/debug/debug-application/
debug-pods.md
debug-running-pod.md
determine-reason-pod-failure.md

tutorials/security/
cluster-level-pss.md
ns-level-pss.md

[sftim]

Tasks are one of [what we see as] the four kinds of documentation; Pods are not.

I wouldn't make a landing page for Pods, but I would try to help someone find all of those pages with at most three clicks starting from https://k8s.io/docs/concepts/workloads/ or https://k8s.io/docs/concepts/containers/

IMO https://kubernetes.io/docs/concepts/workloads/pods/ is pretty usable, although there is room to make it better.

[mrgiles]

Take 3...

1. Divide the _index.md page into 2 docs, with the content presented in the original order:

_index.md

• Overview
• What is a Pod?
• Using Pods
• Workload resources for managing pods
• Working with Pods
• Pod OS
• Pods and controllers
• Pod templates
• Pod update and replacement
• Resource sharing and communication
• Storage in Pods
• Pod networking
• Pod security settings

pod-stat-multi.md

• Static Pods
• Pods with multiple containers
• Container probes

2. Add the missing links to both pages and to the concepts/workloads/_index.md page as @sftim suggested above.
   Would that work? Thanks!

[tengqm]

Some suggestions:

1. Divide the `_index.md` page into 2 docs, with the content presented in the original order:

_index.md

* Overview

* What is a Pod?

* Using Pods

* Workload resources for managing pods

This topic can be split out. There are in general two ways to manage a Pod, you can manipulate the Pod resource directly, or you can delegate that to a workload resource.
The latter one can be on a dedicated page.

* Working with Pods

Maybe we want to combine this topic with the previous topic "Using Pods".

* Pod OS

This is a field for advanced use cases. We may want to discuss this together with overhead, priority, runtimeClassName etc.

* Pods and controllers

* Pod templates

* Pod update and replacement

Pod update and replacement can be reorganized based on the way you are managing them, right?

* Resource sharing and communication

* Storage in Pods

* Pod networking

Both storage and networking are huge topics that warrant their own dedicated pages.

* Pod security settings

pod-stat-multi.md

* Static Pods

* Pods with multiple containers

No. I don't think we want a page named "pod-stat-multi.md". If needed, I'd suggest we add a page "static-pods.md". In that page, we explain the concept, their target use cases, how are they discovered, what are shadow Pods, how are they restarted, their limitations (e.g. references to other resources ...).

Pods with multiple containers? That is a different topic. We can discuss the resource sharing and intra-pod communication there.

* Container probes

I believe we already have a dedicated page on probes. We often receive questions related to probes. Why don't we consolidate them into a single concept page?

2. Add the missing links to both pages and to the `concepts/workloads/_index.md` page as @sftim suggested above.
   Would that work? Thanks!

[sftim]

I like that last suggestion. If you're now convinced @shirady, I suggest you open new issues about each improvement that you support from the outline in #38867 (comment) and close this one.

In other words, don't use this issue as an umbrella issue; “make Pod pages better“ just feels really broad, and might end up with a lot of comments!

---

A detail I think is important -
We already have https://kubernetes.io/docs/concepts/workloads/controllers/ which covers workload management - things that automatically replace Pods. If we added https://kubernetes.io/docs/concepts/workloads/controllers/pod-replacement/ as a new page just about when and how Pods get replaced, I think that's a good fit. The common architectural pattern and its intentional limitations (eg: we never move a Pod to a different node) is core to what makes Kubernetes be Kubernetes.

[mrgiles]

@sftim, should we leave things as they are for now or go ahead and implement some of @tengqm 's suggestions? Thanks.

[sftim]

What I'm suggesting is: a set of new issues, each one capturing a single chunk of the outline @tengqm made earlier - see #38867 (comment)

That will let different authors work on separate packages of the work we're planning. Also, let's say one specific part of that plan does need discussion, we can get on with the other issues from the design without waiting to get every detail agreed. The perfect is the enemy of the good.

[sftim]

If folks want to make a PR that aligns with the overall idea, getting ahead of the issue tracking work: you can! It's open source, and help of all kinds is usually very welcome.

[shirady]

@sftim I'm not sure I understand what you suggested to exactly add in the new issue.
I'm fine if you want to close this issue and open a new one (you can add here the link in the closing comment).