Clarify cluster diagram as one possible reference architecture

[robert-cronin]

This PR addresses the concerns raised in issue #47111 regarding the potential misunderstanding of component distribution in Kubernetes clusters, particularly the presence of kubelet and kube-proxy on control plane nodes.

Before
After

I'm not entirely sure how much additional detail is appropriate for this introductory page on cluster architecture. I'm open to removing certain details for brevity if needed. Feedback on the level of detail and which points are most crucial to keep would be greatly appreciated. Also if there is anything I have gotten wrong about cluster architecture, please feel free to correct me.

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	02c9e9b
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/66ba8cbd2c5bdc00086be5d5
😎 Deploy Preview	https://deploy-preview-47164--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 site configuration.

[neolit123]

i think this is a great addition. thanks
/lgtm

but not sure if the formatting / indentation is correct.

/assign @tengqm
as per your comment on
#47111 (comment)

/sig architecture

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: 15436ba45b96f9a92facd68bf7d93143c71de60b

[robert-cronin]

i think this is a great addition. thanks /lgtm

but not sure if the formatting / indentation is correct.

/assign @tengqm as per your comment on #47111 (comment)

/sig architecture

Thank you for the swift review, @neolit123! I appreciate your feedback on the formatting and indentation. If you're aware of any similar pages with correct formatting, or if you have any specific suggestions for improvement, I'd be grateful for your guidance.

[tamilselvan1102]

page preview: https://deploy-preview-47164--kubernetes-io-main-staging.netlify.app/docs/concepts/architecture/

[neolit123]

would leave the formatting correctness to the docs team.

[sftim]

Thanks

I think if we merged this we'd immediately want to file an issue calling for more changes. You can revise this PR so that it can merge without needing that issue.

Here's some specific feedback.

[robert-cronin]

The latest commit includes the following changes:

• Migrated the text from /docs/concepts/overview/components to /docs/concepts/architecture
• Added a section to /docs/concepts/architecture on the "Architecture Variations"
• Added simple overview to /docs/concepts/overview/components

I'd love any feedback on the overall organization of the content or suggestions on how I can improve the content I added

/docs/concepts/architecture/
Before
After

/docs/concepts/overview/components/
Before
After

[robert-cronin]

Latest commit adds some small points of optimization to make the pages mesh more coherently and make the overview more of an overview.

[network-charles]

/lgtm

[k8s-ci-robot]

@network-charles: changing LGTM is restricted to collaborators

In response to this:

/lgtm

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.

[GarbageYard]

The proposed change mentions following under Node Components section: "These components are essential for node operation but are not always considered part of the core control plane". I have one query: in which case are node components (kubelet and kube-proxy) not considered part of the core control plane?

[sftim]

I have one query: in which case are node components (kubelet and kube-proxy) not considered part of the core control plane?

Always. The control plane does not include the kubelet and kube-proxy; see https://kubernetes.io/docs/concepts/overview/components/

You might run the control plane on a computer (or several) computers that are running kubelet, and possibly also running kube-proxy; however, the control plane is still:

• kube-apiserver
  • and a backing store, canonically etcd
• kube-scheduler
• kube-controller-manager
• (optional) a cloud controller manager to integrate with your cloud provider

[sftim]

/lgtm

Here's some feedback to make this even better.

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: 60b2326103ed6daed7b3bf5b978c2346b78f68d2

[robert-cronin]

@sftim I've added a follow up commit to fix some remaining issues and improve consistency. I am a little confused what the third-party notice is targeting so perhaps my placement is worth double checking. Thanks for the feedback!

[GarbageYard]

@sftim : That's much clearer. Thanks.

However, if that's the case then shouldn't the revised doc mention:
"These components are essential for node operation but are never considered part of the core control plane"
instead of
"These components are essential for node operation but are not always considered part of the core control plane"?

[sftim]

“never“ feels correct to me @GarbageYard

You could think of an electrical generating station. Maybe there is a generator set specifically for the control room (a good idea for resilience), and that generator may be able to supply the plant or even the power network.
However, you wouldn't say that generators are sometimes considered part of the control room.

In that analogy, you could be more specific about why there is a generator in a strange place on the plant diagram. In a Kubernetes cluster, if you run the control plane on nodes, you can explain why some servers are nodes and have both a kubelet and control plane components on them.

[sftim]

/lgtm
/label tide/merge-method-squash

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: d2242616513ea8c876c871323493fa1268bd86aa

[nate-double-u]

This is a really good addition @robert-cronin, thanks so much for writing it up!
(and thanks to all the reviewers too)

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: nate-double-u

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/docs/OWNERS [nate-double-u]

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

[robert-cronin]

This is a really good addition @robert-cronin, thanks so much for writing it up!
(and thanks to all the reviewers too)

/approve

Thank you so much, @nate-double-u, and thanks to all the commenters and reviewers! 😊