Split Pod concept into a simple introduction and further details

shirady commented 1 year ago

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 commented 1 year ago

/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 commented 1 year ago

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 commented 1 year ago

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

devarsh10 commented 1 year ago

Okay @tengqm. /assign

devarsh10 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 7 months ago

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 commented 6 months ago

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 commented 2 months ago

/help

k8s-ci-robot commented 2 months ago

@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](https://github.com/kubernetes/website/issues/38867): >/help Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes-sigs/prow](https://github.com/kubernetes-sigs/prow/issues/new?title=Prow%20issue:) repository.

sftim commented 2 months ago

Help, from any contributor, is welcome.

mrgiles commented 1 month ago

/assign

mrgiles commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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 https://github.com/kubernetes/website/issues/38867#issuecomment-2375441883 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 commented 1 month ago

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

sftim commented 1 month ago

What I'm suggesting is: a set of new issues, each one capturing a single chunk of the outline @tengqm made earlier - see https://github.com/kubernetes/website/issues/38867#issuecomment-2375441883

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 commented 1 month ago

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 commented 1 month ago

@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).

kubernetes / website

Split Pod concept into a simple introduction and further details #38867

Guidelines