Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reword glossary entry for cluster #48686

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Reword glossary entry for cluster #48686

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 9 additions & 10 deletions content/en/docs/reference/glossary/cluster.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,19 @@ id: cluster
date: 2019-06-15
full_link:
short_description: >
A set of worker machines, called nodes, that run containerized applications. Every cluster has at least one worker node.

A set of machines hosting containerized workloads, in the form of pods, and the control plane that manages them.
aka:
tags:
- fundamental
- operation
---
A set of worker machines, called {{< glossary_tooltip text="nodes" term_id="node" >}},
that run containerized applications. Every cluster has at least one worker node.
A set of machines hosting containerized {{< glossary_tooltip text="workloads" term_id="workload" >}}, in the form of {{< glossary_tooltip text="pods" term_id="pod" >}}, and the {{< glossary_tooltip text="control plane" term_id="control-plane" >}} that manages them.
Copy link
Contributor

@sftim sftim Nov 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can do better. Try this:

Suggested change
A set of machines hosting containerized {{< glossary_tooltip text="workloads" term_id="workload" >}}, in the form of {{< glossary_tooltip text="pods" term_id="pod" >}}, and the {{< glossary_tooltip text="control plane" term_id="control-plane" >}} that manages them.
A {{< glossary_tooltip text="control plane" term_id="control-plane" >}} and a set of worker machines that the
control plane manages. A Kubernetes cluster lets you run containerized {{< glossary_tooltip text="workloads" term_id="workload" >}}
as {{< glossary_tooltip text="pods" term_id="pod" >}}.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This depends on the other comment...

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line 14 seems to be missing something?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I revised. BTW you can accept suggestions as is, but you can also incorporate the spirit of the feedback and apply your own edits.


<!--more-->
The worker node(s) host the {{< glossary_tooltip text="Pods" term_id="pod" >}} that are
the components of the application workload. The
{{< glossary_tooltip text="control plane" term_id="control-plane" >}} manages the worker
nodes and the Pods in the cluster. In production environments, the control plane usually
runs across multiple computers and a cluster usually runs multiple nodes, providing
fault-tolerance and high availability.
Machines may be physical or virtual. Machines that host pods are referred to as {{< glossary_tooltip text="nodes" term_id="node" >}}. Nodes that host workloads are referred to as worker nodes. There must be at least one worker node within a cluster.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this isn't correct. A cluster with zero worker nodes isn't very useful, but it's still technically a cluster (maybe you are auto scaling).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah - OK. I kept this as it was part of the previous definition :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revise accordingly.


Control plane components run on one or more of the machines within the cluster. They may execute directly in the context of the operating system of a machine, or within pods. When control plane components run within pods on a machine, the machine may also be referred to as a control plane node.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this isn't correct. You can run the control plane within the cluster, but we actually recommend not doing that for the very best resilience.

Copy link
Author

@TransitivityPaul TransitivityPaul Nov 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK - All of the architecture diagrams show the control plane as being a part of the cluster. I don't mind either way as long as we're consistent. :). This is profoundly important from an architectural perspective. Is this the right place for that discussion?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Control plane:

  • always part of the cluster
  • optional to run it on nodes
  • if you run it on a separate server, the thing you run on a separate server is (if healthy) still logically a control plane, and that logical thing is part of the cluster

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it. I could co-host my control plane instance, with a bunch of other control planes for other clusters, on the same machines. I could host my control plane within another cluster that has it's own control plane.... etc. In tuo capite fiat! Will nudge this and other PRs to reflect. Thx.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please do update this when you have time to.


In production environments, the cluster typically consists of multiple machines, with the control plane components and workloads distributed across them for scale, resilience and high availability. It is a best practice in production environments to have workloads hosted on machines that do not host control plane components.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't formally recommend this topology; we think that a control plane that runs separately from the cluster is an even more resilient choice. However it is up to the cluster operator to make that call, not this project.

It is a best practice in production environments to have workloads hosted on machines that do not host control plane components.

True, but doesn't belong in the glossary. Instead, hyperlink to the page that makes the recommendation.