Labs - KubeVirt quickstart with Minikube

Easy install using minikube

Minikube quickly sets up a local Kubernetes cluster on macOS, Linux, and Windows allowing software developers to quickly get started working with Kubernetes.

Prepare minikube Kubernetes environment

  • A kubectl client is necessary for operating a Kubernetes cluster. It is important to install a kubectl client version that matches the kubernetes version to avoid issues regarding skew.

    To install kubectl client please follow the official documentation for your system using the instructions located here.

Minikube ships a kubectl client version that matches the kubernetes version to avoid skew issues. To use the minikube shipped client do one of the following:

  • All normal kubectl commands should be performed as minikube kubectl
  • It can be added to aliases by running the following:

    alias kubectl='minikube kubectl --'
  • It can be installed directly to the host by running the following:

    VERSION=$(minikube kubectl version | head -1 | awk -F', ' {'print $3'} | awk -F':' {'print $2'} | sed s/\"//g)
    sudo install ${HOME}/.minikube/cache/linux/${VERSION}/kubectl /usr/local/bin
  • To install minikube please follow the official documentation for your system using the instructions located here.

  • Starting minikube can be as simple as running the following command:

    minikube start --cni=flannel


We add the container network interface (CNI) called flannel to make minikube work with VMs that use a masquerade type network interface. If a CNI does not work for you, switch instances of “masquerade” to “bridge” in example VM definitions.

See the minikube handbook here for advanced start options and instructions on how to operate minikube.

Multi-Node Minikube

Minikube has support for adding additional nodes to a cluster. This can be helpful in experimenting with KubeVirt on minikube as some operations like node affinity or live migration require more than one cluster node to demonstrate.

Container Network Interface

By default, minikube sets up a kubernetes cluster using either a virtual machine appliance or a container. For a single node setup, local network connectivity is sufficient. In the case where multiple nodes are involved, even when using containers or VMs on the same host, kubernetes needs to define a shared network to allow pods on one host to communicate with pods on the other host. To this end, minikube supports a number of Container Network Interface (CNI) plugins the simplest of which is flannel.

Updating the minikube start command

To have minikube start up with the flannel CNI plugin over two nodes, alter the minikube start command:

minikube start --nodes=2 --cni=flannel

Core DNS race condition

An issue has been reported where the coredns pod in multi-node minikube comes up with the wrong IP address. If this happens, kubevirt will fail to install properly. To work around, delete the coredns pod from the kube-system namespace and disable/enable the kubevirt addon in minikube.

Deploy KubeVirt

KubeVirt can be installed using the KubeVirt operator, which manages the lifecycle of all the KubeVirt core components.

Below are two examples of how to install KubeVirt using the latest release.

The easy way

Addon currently broken

An issue has been reported where more recent versions of minikube break the kubevirt addon. Fall back to the “in-depth” section below until this is resolved.

  • Installing KubeVirt can be as simple as the following command:

    minikube addons enable kubevirt

The in-depth way

  • Use kubectl to deploy the KubeVirt operator:

    export VERSION=$(curl -s
    echo $VERSION
    kubectl create -f${VERSION}/kubevirt-operator.yaml

Nested virtualization

If the minikube cluster runs on a virtual machine consider enabling nested virtualization. Follow the instructions described here. If for any reason nested virtualization cannot be enabled do enable KubeVirt emulation as follows:

kubectl -n kubevirt patch kubevirt kubevirt --type=merge --patch '{"spec":{"configuration":{"developerConfiguration":{"useEmulation":true}}}}'
  • Again use kubectl to deploy the KubeVirt custom resource definitions:

    kubectl create -f${VERSION}/kubevirt-cr.yaml

Verify components

By default KubeVirt will deploy 7 pods, 3 services, 1 daemonset, 3 deployment apps, 3 replica sets.

  • Check the deployment:

    kubectl get -n kubevirt -o=jsonpath="{.status.phase}"
  • Check the components:

    kubectl get all -n kubevirt
  • When using the minikube KubeVirt addon check logs of the kubevirt-install-manager pod:

    kubectl logs pod/kubevirt-install-manager -n kube-system


KubeVirt provides an additional binary called virtctl for quick access to the serial and graphical ports of a VM and also handle start/stop operations.


virtctl can be retrieved from the release page of the KubeVirt github page.

  • Run the following:
    VERSION=$(kubectl get -n kubevirt -o=jsonpath="{.status.observedKubeVirtVersion}")
    ARCH=$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/') || windows-amd64.exe
    echo ${ARCH}
    curl -L -o virtctl${VERSION}/virtctl-${VERSION}-${ARCH}
    chmod +x virtctl
    sudo install virtctl /usr/local/bin

Install as Krew plugin

virtctl can be installed as a plugin via the krew plugin manager. Occurrences of virtctl <command>... can then be read as kubectl virt <command>....

  • Run the following to install:
    kubectl krew install virt

What’s next: Labs

After you have deployed KubeVirt you can work through the labs to help you get acquainted with KubeVirt and how it can be used to create and deploy VMs with Kubernetes.

The first lab is “Use KubeVirt”. This lab walks through the creation of a Virtual Machine Instance (VMI) on Kubernetes and then how virtctl is used to interact with its console.

The second lab is “Experiment with CDI”. This lab shows how to use the Containerized Data Importer (CDI) to import a VM image into a Persistent Volume Claim (PVC) and then how to attach the PVC to a VM as a block device.

The third lab is “KubeVirt upgrades”. This lab shows how easy and safe is to upgrade the KubeVirt installation with zero down-time.

Found a bug?

We are interested in hearing about your experience.

Please report any problems to the issue tracker.