Page title “Creating a single control-plane cluster with kubeadm” could mislead

[sftim]

This is a Bug Report

Problem:
The title of https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/ used to be
“Creating a single master cluster with kubeadm” and PR #14594 changed that to “Creating a single control-plane cluster with kubeadm” to match guidelines on terminology. However, the current title does not read as idiomatic English and could also mislead readers.

All Kubernetes clusters should have exactly 1 control plane. You might have 0 control planes I suppose, in which case you need to fix that so that your workloads remain managed. You can't have 2 control planes for 1 cluster. What you can do is run your control plane across multiple hosts and even zones, to provide resilience. For that reason, it isn't the control plane that is single; instead, this page explains how to deploy a cluster where the control plane runs on only one computer.

Proposed Solution:
Change the title of the page. Pick wording that makes it clear that it's a simple cluster setup and isn't suitable for keeping your cluster within a low error budget (this is because if the one control plane host fails then you lose all control loops, the persisted data in etcd, and the Kubernetes cluster API). You don't need to go into all that detail so long as the reader is aware that another page explains how to do roughly the same thing but with availability taken into consideration.

Also reword the following text from the body of the page:

Install a single control-plane Kubernetes cluster or high-availability cluster

Optionally, add or revise introductory text to clarify the limitations of what this page is teaching. For example, consider if text “a minimum viable Kubernetes cluster that conforms to best practices” is the right fit?

Page to Update:
https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/

Additional Information:
/sig cluster-lifecycle
/language en
/kind cleanup
/priority backlog
/good-first-issue

If you're looking to pick this up as a first issue and would like advice, go ahead and reply - a Kubernetes contributor will help you to get started.
Also, because this issue is not especially urgent, if you have already made a few contributions to this documentation, please consider leaving this one as a starting point for someone new.

[k8s-ci-robot]

@sftim:
This request has been marked as suitable for new contributors.

Please ensure the request meets the requirements listed here.

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

In response to this:

This is a Bug Report

Problem:
The title of https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/ used to be
“Creating a single control-plane cluster with kubeadm” and PR #14594 changed that to “Creating a single control-plane cluster with kubeadm” to match guidelines on terminology. However, the current title does not read as idiomatic English and could also mislead readers.

All Kubernetes clusters should have exactly 1 control plane. You might have 0 control planes I suppose, in which case you need to fix that so that your workloads remain managed. You can't have 2 control planes for 1 cluster. What you can do is run your control plane across multiple hosts and even zones, to provide resilience. For that reason, it isn't the control plane that is single; instead, this page explains how to deploy a cluster where the control plane runs on only one computer.

Proposed Solution:
Change the title of the page. Pick wording that makes it clear that it's a simple cluster setup and isn't suitable for keeping your cluster within a low error budget, because if the one control plane host fails then you lose all control loops, the persisted data in etcd, and the Kubernetes cluster API.

Optionally, add or revise introductory text to clarify the limitations of what this page is teaching. For example, consider if text “a minimum viable Kubernetes cluster that conforms to best practices” is the right fit?

Page to Update:
https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/

Additional Information:
/sig cluster-lifecycle
/language en
/kind cleanup
/priority backlog
/good-first-issue

If you're looking to pick this up as a first issue and would like advice, go ahead and reply - a Kubernetes contributor will help you to get started.
Also, because this issue is not especially urgent, if you have already made a few contributions to this documentation, please consider leaving this one as a starting point for someone new.

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/test-infra repository.

[neolit123]

Change the title of the page. Pick wording that makes it clear that it's a simple cluster setup and isn't suitable for keeping your cluster within a low error budget (this is because if the one control plane host fails then you lose all control loops, the persisted data in etcd, and the Kubernetes cluster API). You don't need to go into all that detail so long as the reader is aware that another page explains how to do roughly the same thing but with availability taken into consideration.

my vote goes for:
"Creating a cluster with kubeadm"
and the page should link to the HA guide which is an optional extension.

Install a single control-plane Kubernetes cluster or high-availability cluster

Optionally, add or revise introductory text to clarify the limitations of what this page is teaching. For example, consider if text “a minimum viable Kubernetes cluster that conforms to best practices” is the right fit?

"Creating a minimum viable Kubernetes cluster that conforms to best practices", seems good to me.

The HA guide link (link under "high-availability cluster") can be moved under "higher availabilty" in this sentence:
"Use multiple control-plane nodes. You can read Options for Highly Available topology to pick a cluster topology that provides higher availabilty."

it's currently a bullet item here:
https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#resilience

[Evalle]

I think I can help with this one, if it's OK
/assign

[sftim]

Anyone is welcome to open a pull request that makes the changes suggested, or otherwise helps get the issue done.