How to setup Minikube with KVM on Ubuntu

Since Docker CE doesn’t support Kubernetes out of the box (like Docker for Windows/Mac) it’s up to us to figure out how to run it for local development. Using Minikube with KVM we can fairly painlessly get our environment running.

This guide builds upon the How to setup Docker CE on Ubuntu post I previously wrote. If you haven’t yet installed and configured Docker, you may wish to follow that guide first. If you choose not to install Docker and you encounter any issues please let me know on Twitter.

Install KVM

KVM (Kernel-based Virtual Machine) turns the Linux kernel into a hypervisor, giving us a lightweight virtual machine.

First update your repositories:

sudo apt update

Then install everything we need for KVM:

sudo apt install \
    qemu-kvm \
    libvirt-clients \
    libvirt-daemon-system \
    bridge-utils \
    virt-manager

Add your user to the libvirt group, so that you can run commands for starting/stopping KVM virtual machines without sudo:

sudo usermod -a -G libvirt $(whoami)

Then either fully logout and log back in… or take the shortcut and add your current session to the libvirt group with this command:

newgrp libvirt

Install kubectl

Kubectl is the command you’ll use for interacting with your Minikube (and any other Kubernetes clusters). If you don’t have Kubectl yet, you can install it as a snap:

sudo snap install kubectl --classic

If you’re anything like me, I can’t function without bash completions for most commands, you can install them for kubectl with the following command (assuming you’re on bash):

echo "source <(kubectl completion bash)" >> ~/.bashrc

Then, to get the completions in your current terminal session (without reloading .bashrc) run:

source <(kubectl completion bash)

Then perform one of the following to see the kubectl completions work:

Open a new terminal window
Run source ~/.bashrc to receive the update in your current terminal session
Run `` to source the completions into your current terminal session

Install minikube

The Minikube GitHub repo provides a command to download and install the Minikube binary. I’ve included the command below with line breaks for readability.

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

Like kubectl Minikube includes its completions with the binary, however it’s intended to be installed into the bash completions directory:

minikube completion bash | sudo tee /etc/bash_completion.d/minikube

To see the Minikube completions in your current terminal you’ll need to source the completions:

source <(minikube completion bash)

Install KVM2 driver

Minikube is replacing the current KVM driver with their own driver called kvm2 to install the driver run the following command (or get it from the official source—note you already installed the dependencies):

curl -Lo docker-machine-driver-kvm2 https://storage.googleapis.com/minikube/releases/latest/docker-machine-driver-kvm2 \
&& chmod +x docker-machine-driver-kvm2 \
&& sudo cp docker-machine-driver-kvm2 /usr/local/bin/ \
&& rm docker-machine-driver-kvm2

Run Minikube with KVM2 driver

To start Minikube with the KVM2 driver run:

minikube start --vm-driver kvm2

Note, this will take a while to run, be patient.

If you receive an error, you probably previously installed Minikube and had a failure run this to try to resolve it:

# Cleanup after any old/failed minikube
minikube delete
rm -fr ~/.minikube/

# Attempt to start with kvm2 again
minikube start --vm-driver kvm2

You should now be able to run minikube status and see that minikube is running.

Handle KVM network issue

To avoid an issue you’ll hit after a reboot, you should now run:

virsh net-autostart minikube-net

The issue that you would otherwise see upon running minikube start --vm-driver kvm2 is an error that looks like this:

Starting local Kubernetes v1.10.0 cluster...
Starting VM...
E0912 09:37:27.685832   22579 start.go:174] Error starting host: Error starting stopped host: Error creating VM: virError(Code=55, Domain=19, Message='Requested operation is not valid: network 'minikube-net' is not active').

 Retrying.
E0912 09:37:27.686080   22579 start.go:180] Error starting host:  Error starting stopped host: Error creating VM: virError(Code=55, Domain=19, Message='Requested operation is not valid: network 'minikube-net' is not active')
================================================================================
An error has occurred. Would you like to opt in to sending anonymized crash
information to minikube to help prevent future errors?
To opt out of these messages, run the command:
        minikube config set WantReportErrorPrompt false
================================================================================
Please enter your response [Y/n]:

If you do hit this error, you’ll need to start the minikube-net in virsh then re-run your start command:

virsh net-start minikube-net

Next steps

Now that Minikube is up and running there are a few features you may want to explore, or if you’re coming from Docker for Mac or Docker for Windows may trip you up.

Host directory mounting

If you’re coming from Docker for Mac/Windows, Docker set this up for you automatically via the UI (where you choose the disk to share with Docker).

With Minikube, you’ll need to mount any host directories you wish to share with your pods via the minikube mount command. The command looks like this:

minikube mount [HOST DIRECTORY]:[VM DIRECTORY]

If you want to share a directory named Project’s in your home, you’d run:

minikube mount /home/$(whoami)/Projects:/home/$(whoami)/Projects

Kubernetes dashboard

Minikube bundles the Kubernetes dashboard and Heapster in, so to access the dashboard simply run:

minikube dashboard

Make Docker commands use Minikube’s Docker daemon

When you’re building Docker images in your host machine and attempt to run those images within your Minikube’s Kubernetes cluster, you’ll discover that Minikube is unable to find your Docker image. This is because your Docker image was created in your host but the Docker instance of Kubernetes is within the virtual machine.

Minikube includes a command that will set your host terminal session to use the Docker host within the VM:

eval $(minikube docker-env)

Once you run this, you can then re-build your local Docker image—this time in the VM. Now when you try to deploy the image to Kubernetes it will work.

Something that I ran into with this is that when I open a new terminal session these settings no longer apply, so whenever I am building Docker images that I intead to run within Minikube I need to remember to execute this command.

You may wish to create an alias for yourself to ease this burden.