Issue with k8s.io/docs/tasks/tools/: Difference between Minikube and Kind is not clear

[guettli]

On this page it is not clear why there are two tools: Minikube and Kind:

https://kubernetes.io/docs/tasks/tools/

This confuses new users.

---

[extra details added by @sftim]
Here's how someone could fix that:

• instead, we write a new page that lists different ways to set up a learning environment
  • the new page would have the URL https://kubernetes.io/docs/setup/learning-environment/ (replacing the existing stub)
  • there is a redirect in static/_redirects that you must remove
  • the page should help people choose what environment to select based on what they want to learn
  • there should be a mix of signposting and summaries to help people understand what a Kubernetes is, because the target audience is clearly still learning
• make it clear that people should install kubectl as well (and link to https://kubernetes.io/docs/tasks/tools/#kubectl)
• a phrase like “if you're not sure, pick Minikube” is appropriate
  • kind requires that you have either Docker or Podman installed, and maybe that isn't what you wanted
  • kubeadm installs are a lot to cover for a beginner
    and also link to https://kubernetes.io/docs/tutorials/hello-minikube/ so that people know what to do next
• as well as the simple option, add more details for people who want to know more, behind a <details> element.
  • if you don't reveal the details option, the page signposts you to set up minikube and kubectl
  • if you do reveal the details option, the page tells you that kind is another common choice, then gives readers more
    information to help them choose an approach based on their needs.
  • it's OK to link to external guides where these are appropriate for readers' needs and we can have reasonable confidence that these links will stay relevant

Optional extra improvements: update https://minikube.sigs.k8s.io/docs/start/ to link back to https://kubernetes.io/docs/tutorials/hello-minikube/

• optionally, we can also mention that there are proprietary options and link to a selection.
  • be wary of confusing people if linking to Docker Desktop!
• optionally, also link to https://github.com/kelseyhightower/kubernetes-the-hard-way, or to a shortlink that we set up for the purpose (eg https://k8s.io/kubernetes-the-hard-way)
  • maybe there's a curated list of alternatives; Kelsey Hightower's original is GCP specific
• link to https://k8s.io/docs/setup/production-environment/ - ideally written so people are clear that there's more to learn later and, actually, that they don't need to learn it all right away.

[sftim]

There are in fact more than two tools you can use to run a local cluster. We should make it more clear that kind and Minikube are just two examples and that there are others (available from third parties).

/language en

[annajung]

I agree that adding some clarification will help.
Modification needs to be made to tools index page

/triage accepted
/good-first-issue

[guettli]

There are in fact more than two tools you can use to run a local cluster. We should make it more clear that kind and Minikube are just two examples and that there are others (available from third parties).

/language en

Wait, wait, wait. Yes, there are even more tools available. But my problem is: I have no clue which one too choose. If you add even more alternatives, then the situation for a first-time-user is getting even more difficult.

When I compiled the linux kernel in the year 1997 I had no clue about all these questions you got asked during this process. But there was always a "if unsure use ..." advice. This helped me to get it done.

It would be great if the docs could provide something like "if unsure use ...".

[Lucifergene]

/assign

[afbjorklund]

It's actually three tools, on that page: minikube, kind, kubeadm (the first two are using the third one internally, but anyway).

Install Tools

• kubectl
• kind
• minikube
• kubeadm

I guess the main difference here would be the "requires that you have Docker installed and configured" part, for kind ?

• Docs: Why not minikube? kubernetes-sigs/kind#2577

• Document differences between kind and kic minikube#12104

https://kubernetes.io/blog/2016/09/how-we-made-kubernetes-easy-to-install/ has some more text about kubeadm

---

It was the topic of one of the KubeCon EU 21 talks, about the three* different development environments for Kubernetes.

* normally it is talked about "Docker" as one environment, even if it is two very different products: Engine and Desktop

https://sched.co/iE7w

[sftim]

within https://kubernetes.io/docs/setup/, “Learning environment” at the moment redirects to the tools download page and provides no extra context

Here's how someone could fix that:

• instead, we write a new page that lists different ways to set up a learning environment
  • the page should help people choose what environment to select based on what they want to learn
  • there should be a mix of signposting and summaries to help people understand what a Kubernetes is, because the target audience is clearly still learning
• a phrase like “if you're not sure, pick Minikube” is appropriate
  • kind requires that you have either Docker or Podman installed, and maybe that isn't what you wanted
  • kubeadm installs are a lot to cover for a beginner
• that diagram, or one like it, would be useful. Maybe without the emphasis on Docker, and without the Tux logo either. We don't use the Tux logo elsewhere
• optionally, we can also mention that there are proprietary options and link to a selection.
  • be wary of confusing people if linking to Docker Desktop!
• optionally, also link to https://github.com/kelseyhightower/kubernetes-the-hard-way, or to a shortlink that we set up for the purpose (eg https://k8s.io/kubernetes-the-hard-way)
  • maybe there's a curated list of alternatives; Kelsey Hightower's original is GCP specific

[sftim]

@guettli what do you think of the suggestion there?

[afbjorklund]

• without the emphasis on Docker, and without the Tux logo either

"Docker" was supposed to represent 1) any container engine for running the system containers
2) any container runtime for use with Kubernetes. It gets a bit complex with the Docker-in-Docker

1: such as docker, podman, ...
2: such as docker, cri-o, containerd, ...

"Tux" was supposed to represent the Linux kernel, and the grey chip any other OS kernel (including Linux)
It went to show that Kubernetes (control-plane, at least) is a Linux-only program, at the moment

So when not running Linux, you need to use virtualization

When you are running Linux, you can use virtualization

It also used "VirtualBox" to represent hypervisors, which is also not very relevant after going multiarch.
But it was the only one widely known, and the others vary by platform: hyper-v, xhyve, libvirt, etc. etc.

---

This overview even assumed that Linux is an OS, and that you didn't have to choose between distributions

So the one hand it makes things easier for the newcomer, but on the other hand it hides the number of paths

It's a tradeoff between "Hello, World"* and scaring people.

* https://kubernetes.io/docs/tutorials/hello-minikube/

Preferably, there would be an easy way to just get started.

https://en.wikipedia.org/wiki/Shuhari

This is what minikube start is trying to do (I might be biased), and then offer choice in form of options.

I would love to see an advanced Kubernetes From Scratch effort as well, similar to Linux From Scratch.