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

Reconcile the minikube install page with best practices #20717

Closed
wants to merge 6 commits into from
Closed

Reconcile the minikube install page with best practices #20717

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
63b313c
Reconcile the minikube installation page with best practices
tstromberg May 1, 2020
3d8cd27
Address review comments
tstromberg May 6, 2020
10c3132
Remove extraneous newline
tstromberg May 6, 2020
bb55d28
Merge branch 'master' into reconcile-minikube
tstromberg May 7, 2020
c36506a
Address kbhawkey's review comments
tstromberg May 7, 2020
046216e
Move whatsnext to end, simplify assistance text
tstromberg May 7, 2020
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
223 changes: 35 additions & 188 deletions content/en/docs/tasks/tools/install-minikube.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Install Minikube
title: Install minikube
content_template: templates/task
weight: 20
card:
Expand All @@ -9,253 +9,100 @@ card:

{{% capture overview %}}

This page shows you how to install [Minikube](/docs/tutorials/hello-minikube), a tool that runs a single-node Kubernetes cluster in a virtual machine on your personal computer.
This page shows you how to install [minikube](https://minikube.sigs.k8s.io/), a tool that runs a Kubernetes cluster on your personal computer.

{{% /capture %}}

{{% capture prerequisites %}}

{{< tabs name="minikube_before_you_begin" >}}
{{% tab name="Linux" %}}
To check if virtualization is supported on Linux, run the following command and verify that the output is non-empty:
```
grep -E --color 'vmx|svm' /proc/cpuinfo
```
{{% /tab %}}

{{% tab name="macOS" %}}
To check if virtualization is supported on macOS, run the following command on your terminal.
```
sysctl -a | grep -E --color 'machdep.cpu.features|VMX'
```
If you see `VMX` in the output (should be colored), the VT-x feature is enabled in your machine.
{{% /tab %}}

{{% tab name="Windows" %}}
To check if virtualization is supported on Windows 8 and above, run the following command on your Windows terminal or command prompt.
```
systeminfo
```
If you see the following output, virtualization is supported on Windows.
```
Hyper-V Requirements: VM Monitor Mode Extensions: Yes
Virtualization Enabled In Firmware: Yes
Second Level Address Translation: Yes
Data Execution Prevention Available: Yes
```
To run minikube, you'll need:

If you see the following output, your system already has a Hypervisor installed and you can skip the next step.
```
Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed.
```


{{% /tab %}}
{{< /tabs >}}
* A host with administrator privileges (for example, ability to `sudo` or `Run as Administrator`)
tstromberg marked this conversation as resolved.
Show resolved Hide resolved
* 2GiB of free memory
* 20GiB of free disk space
* Internet connection
* A compatible container or virtual machine manager, such as: [Docker](https://minikube.sigs.k8s.io/docs/docs/drivers/docker), [Hyperkit](https://minikube.sigs.k8s.io/docs/docs/drivers/hyperkit), [Hyper-V](https://minikube.sigs.k8s.io/docs/docs/drivers/hyperv), [KVM](https://minikube.sigs.k8s.io/docs/docs/drivers/kvm2), [Parallels](https://minikube.sigs.k8s.io/docs/docs/drivers/parallels), [Podman](https://minikube.sigs.k8s.io/docs/docs/drivers/podman), [VirtualBox](https://minikube.sigs.k8s.io/docs/docs/drivers/virtualbox), or [VMWare](https://minikube.sigs.k8s.io/docs/docs/drivers/vmware)
tstromberg marked this conversation as resolved.
Show resolved Hide resolved

{{% /capture %}}

{{% capture steps %}}

# Installing minikube
## Installing minikube

{{< tabs name="tab_with_md" >}}
{{% tab name="Linux" %}}

### Install kubectl

Make sure you have kubectl installed. You can install kubectl according to the instructions in [Install and Set Up kubectl](/docs/tasks/tools/install-kubectl/#install-kubectl-on-linux).
For Linux users, there are 3 easy download options:
tstromberg marked this conversation as resolved.
Show resolved Hide resolved

### Install a Hypervisor

If you do not already have a hypervisor installed, install one of these now:

• [KVM](https://www.linux-kvm.org/), which also uses QEMU

• [VirtualBox](https://www.virtualbox.org/wiki/Downloads)

Minikube also supports a `--driver=none` option that runs the Kubernetes components on the host and not in a VM.
Using this driver requires [Docker](https://www.docker.com/products/docker-desktop) and a Linux environment but not a hypervisor.

If you're using the `none` driver in Debian or a derivative, use the `.deb` packages for
Docker rather than the snap package, which does not work with Minikube.
You can download `.deb` packages from [Docker](https://www.docker.com/products/docker-desktop).

{{< caution >}}
The `none` VM driver can result in security and data loss issues.
Before using `--driver=none`, consult [this documentation](https://minikube.sigs.k8s.io/docs/reference/drivers/none/) for more information.
{{< /caution >}}

Minikube also supports a `vm-driver=podman` similar to the Docker driver. Podman run as superuser privilege (root user) is the best way to ensure that your containers have full access to any feature available on your system.

{{< caution >}}
The `podman` driver requires running the containers as root because regular user accounts don’t have full access to all operating system features that their containers might need to run.
{{< /caution >}}

### Install Minikube using a package

There are *experimental* packages for Minikube available; you can find Linux (AMD64) packages
from Minikube's [releases](https://github.com/kubernetes/minikube/releases) page on GitHub.

Use your Linux's distribution's package tool to install a suitable package.

### Install Minikube via direct download

If you're not installing via a package, you can download a stand-alone
binary and use that.
### Binary download

```shell
curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 \
&& chmod +x minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
```

Here's an easy way to add the Minikube executable to your path:
### Debian package

```shell
sudo mkdir -p /usr/local/bin/
sudo install minikube /usr/local/bin/
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube_latest_amd64.deb
sudo dpkg -i minikube_latest_amd64.deb
```

### Install Minikube using Homebrew

As yet another alternative, you can install Minikube using Linux [Homebrew](https://docs.brew.sh/Homebrew-on-Linux):
### RPM package

```shell
brew install minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-latest.x86_64.rpm
sudo rpm -ivh minikube-latest.x86_64.rpm
```

{{% /tab %}}
{{% tab name="macOS" %}}
### Install kubectl

Make sure you have kubectl installed. You can install kubectl according to the instructions in [Install and Set Up kubectl](/docs/tasks/tools/install-kubectl/#install-kubectl-on-macos).

### Install a Hypervisor

If you do not already have a hypervisor installed, install one of these now:

• [HyperKit](https://github.com/moby/hyperkit)

• [VirtualBox](https://www.virtualbox.org/wiki/Downloads)

• [VMware Fusion](https://www.vmware.com/products/fusion)

### Install Minikube
The easiest way to install Minikube on macOS is using [Homebrew](https://brew.sh):
If the [Brew Package Manager](https://brew.sh/) is installed:

```shell
brew install minikube
```

You can also install it on macOS by downloading a stand-alone binary:

```shell
curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-amd64 \
&& chmod +x minikube
```

Here's an easy way to add the Minikube executable to your path:
Otherwise, download minikube directly:

```shell
sudo mv minikube /usr/local/bin
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-amd64
sudo install minikube-darwin-amd64 /usr/local/bin/minikube
```

{{% /tab %}}
{{% tab name="Windows" %}}
### Install kubectl

Make sure you have kubectl installed. You can install kubectl according to the instructions in [Install and Set Up kubectl](/docs/tasks/tools/install-kubectl/#install-kubectl-on-windows).

### Install a Hypervisor

If you do not already have a hypervisor installed, install one of these now:

• [Hyper-V](https://msdn.microsoft.com/en-us/virtualization/hyperv_on_windows/quick_start/walkthrough_install)

• [VirtualBox](https://www.virtualbox.org/wiki/Downloads)

{{< note >}}
Hyper-V can run on three versions of Windows 10: Windows 10 Enterprise, Windows 10 Professional, and Windows 10 Education.
{{< /note >}}

### Install Minikube using Chocolatey

The easiest way to install Minikube on Windows is using [Chocolatey](https://chocolatey.org/) (run as an administrator):
If the [Chocolatey](https://chocolatey.org/) package manager is installed, use it to install minikube:

```shell
choco install minikube
```

After Minikube has finished installing, close the current CLI session and restart. Minikube should have been added to your path automatically.

### Install Minikube using an installer executable

To install Minikube manually on Windows using [Windows Installer](https://docs.microsoft.com/en-us/windows/desktop/msi/windows-installer-portal), download [`minikube-installer.exe`](https://github.com/kubernetes/minikube/releases/latest/download/minikube-installer.exe) and execute the installer.

### Install Minikube via direct download

To install Minikube manually on Windows, download [`minikube-windows-amd64`](https://github.com/kubernetes/minikube/releases/latest), rename it to `minikube.exe`, and add it to your path.
Otherwise, download and run the [Windows installer](https://storage.googleapis.com/minikube/releases/latest/minikube-installer.exe).

{{% /tab %}}
{{< /tabs >}}


{{% /capture %}}

{{% capture whatsnext %}}

* [Running Kubernetes Locally via Minikube](/docs/setup/learning-environment/minikube/)

{{% /capture %}}

## Confirm Installation

To confirm successful installation of both a hypervisor and Minikube, you can run the following command to start up a local Kubernetes cluster:

{{< note >}}
## Starting your first cluster

For setting the `--driver` with `minikube start`, enter the name of the hypervisor you installed in lowercase letters where `<driver_name>` is mentioned below. A full list of `--driver` values is available in [specifying the VM driver documentation](https://kubernetes.io/docs/setup/learning-environment/minikube/#specifying-the-vm-driver).

{{< /note >}}

```shell
minikube start --driver=<driver_name>
```

Once `minikube start` finishes, run the command below to check the status of the cluster:
Run:

```shell
minikube status
```

If your cluster is running, the output from `minikube status` should be similar to:

```
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured
minikube start
```

After you have confirmed whether Minikube is working with your chosen hypervisor, you can continue to use Minikube or you can stop your cluster. To stop your cluster, run:

```shell
minikube stop
```
minikube will automatically select an appropriate driver, but will mention alternatives if available. For additional information or assistance, please see:

## Clean up local state {#cleanup-local-state}
* [minikube documentation](https://minikube.sigs.k8s.io/docs)
* [#minikube chat on Slack](https://kubernetes.slack.com/archives/C1F5CT6Q1)
* [minikube issues on GitHub](https://github.com/kubernetes/minikube/issues)

If you have previously installed Minikube, and run:
```shell
minikube start
```
{{% capture whatsnext %}}

and `minikube start` returned an error:
```
machine does not exist
```
* [Running Kubernetes locally via minikube](/docs/setup/learning-environment/minikube/)
tstromberg marked this conversation as resolved.
Show resolved Hide resolved

then you need to clear minikube's local state:
```shell
minikube delete
```
{{% /capture %}}