"Creating a cluster with kubeadm"—there should be a simple, straightforward quickstart

[jonassteinberg1]

Just wanted to give some feedback as a relatively experienced kubernetes operator with zero kubeadm experience. I'm very surprised at the approach that is taken within the document Creating A Cluster With kubeadm. It is extremely high-level to the point of vagueness. Yes there are a couple literal commands suggested to be run, but there is no workflow that actually involves creating a cluster. If you title a document, "Creating A Cluster With kubeadm" that document should in my opinion not be a general document about the potential ways to create a cluster, but instead culminate in the actual creation of a cluster. Whatever the case the kubeadm documentation is high-level and sprawling and yet offers no concrete document that just gets someone "up and running with a vanilla single or two-node cluster". Someone clearly put a lot of time into writing these documents, but as with 99% of official kubernetes documentation pragmatism would be much more valuable than scope. Decouple the man page stuff for something like api or configuration documentation. I realize it may be tempting to suggest that I myself rewrite this given that it is an open source project, though that is entirely beside the point. I am coming to this documentation as a first time user; I expect the last impression that the author wants to give is that the documentation requires studying to be useful -- that should not be the case and can come second. Someone has taken weeks I'm betting to write this documentation and that person is clearly a master of kubeadm. That person should evolve and come back and write a quickstart or else what's the point of any of it, frankly?

[stmcginnis]

Hmm, I've used this page several times to walk through spinning up a cluster successfully. Are there specific sections or flows that you find lacking? You mention a couple general concepts, but this still kind of reads as "this should be better!!"

[jonassteinberg1]

I read half the document word-for-word and then skimmed the rest. Hopefully the meat comes in the second half? Either way: consider if the meat comes after the vegetables? Normally this is considered backwards. Also: the generality of the document is the catalyst for my thesis being, "this should be better," as you put it. I'm not in the habit of rewriting someone else's documentation. But...I will scrutinize the hell out of this and see if a cluster pops out.

…

On Fri, Feb 23, 2024, 1:06 PM Sean McGinnis ***@***.***> wrote: Hmm, I've used this page several times to walk through spinning up a cluster successfully. Are there specific sections or flows that you find lacking? You mention a couple general concepts, but this still kind of reads as "this should be better!!" — Reply to this email directly, view it on GitHub <#45309 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AO4VO5TLQCM3JGKNOQ3MUN3YVDSCPAVCNFSM6AAAAABDXFP5B2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRRHA2DONJQGY> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[sftim]

What we have now could split into two explanations:

• what's involved, generally, in cluster setup
  • how kubeadm fits into that story
• a tutorial-like page about how to set up a multi node cluster with a stacked etc, 3 × n control plane nodes, m worker nodes
  • you would need to pick your own container runtime and network plugin, so one of the subtasks is to prepare for the work by picking something
  • we should also explain how to check that your cluster is happy and healthy
  • a “what's next” for this page should help you find separate advice about deploying optional but common add-ons, such as the metrics server

The tutorial I'm imagining is a largely manual walkthrough. There is third party documentation from the ecosystem but we don't document that, as (so far as I know) all of these tools are either aimed as local Kubernetes development, or are not part of Kubernetes.

[sftim]

/language en
/sig cluster-lifecycle

/frozen
We should do this
/retitle "Creating a cluster with kubeadm—there should be a simple, straightforward quickstart”

Even if we try hard, it won't be simple and straightforward, but we can do more than we have.

[sftim]

Someone has taken weeks I'm betting to write this documentation and that person is clearly a master of kubeadm.

I think this might be the work of more than one contributor, not the product of a single expert.

[sftim]

To move this work forward, a contributor can:

• look at the page
• identify actionable subtasks to help reshape the existing content
• file a new separate issue for some or all of those actionable subtasks

[jonassteinberg1]

@sftim okay here are the tasks:

1. rename Creating a cluster with kubeadm to Cluster Creation Deep Dive to make it clear that the document is going to cover various considerations and configuration options.
2. create a quickstart document called Cluster Creation Quickstart and then use the kubeadm cli STDOUT in it:

    │ KUBEADM │
    │ Easily bootstrap a secure Kubernetes cluster │

    │ Please give us feedback at: │
    │ https://github.com/kubernetes/kubeadm/issues │

Example usage:

    Create a two-machine cluster with one control-plane node
    (which controls the cluster), and one worker node
    (where your workloads, like Pods and Deployments run).

    │ On the first machine: │
    │ control-plane# kubeadm init │

    │ On the second machine: │
    │ worker# kubeadm join <arguments-returned-from-init> │

    You can then repeat the second step on as many other machines as you like.

The quickstart document, unlike the original document, should:

• assume people are using yum/dnf or apt server os's
• assume people have a container runtime installed
• simply link to installing a cri plugin
• not diverge into various potential kubeadm cli switch options in an attempt to be a catchall that covers the myriad potential pre-existing OS or cluster states folks may be coming in
• state at the top of the doc "if you are coming to this page with anything but a fresh install see the deep dive document"
• list some basic remediation commands for various errors (yes I know there is a troubleshooting doc, it does not need to overtake that)
• be 80% commands and 20% words

If you want to see an excellent example of a similarly complicated tool that has a legitimate quickstart that I was able to follow and complete in a matter of minutes look no further than Calico:

https://docs.tigera.io/calico/latest/getting-started/kubernetes/quickstart

[sftim]

To move this work forward, a contributor can:

• look at the page
• identify actionable subtasks to help reshape the existing content - see "Creating a cluster with kubeadm"—there should be a simple, straightforward quickstart #45309 (comment) for a hint
• file a new separate issue for some or all of those actionable subtasks

[sftim]

/triage accepted