Setting Up the Virtualization Environment

Overview

Follow the appropriate procedure to set up the hypervisor for your particular operating system. Minishift uses libmachine and its driver plug-in architecture to provide a consistent way to manage the Minishift VM.

Some hypervisors require manual installation of the driver plug-in. Minishift embeds the VirtualBox driver plug-in, so no additional steps are required to configure it. However, VirtualBox will need to be identified to Minishift via the --vm-driver virtualbox flag or persistant configuration settings. See Setting Up Minishift to Use VirtualBox for more information.

See the appropriate section for your hypervisor and operating system:

• For Linux, set up the KVM driver

• For macOS, set up the xhyve driver or set up the hyperkit driver

• For Windows, set up the Hyper-V driver

• For VirtualBox, set up Minishift to use VirtualBox

Linux

Setting Up the KVM Driver

Minishift is currently tested against docker-machine-driver-kvm version 0.10.0.

Proceed to the instructions for your Linux distribution after you have set up the docker-machine-driver-kvm binary.

For more information, see the GitHub documentation of the Docker Machine KVM driver.

On Ubuntu

1. Install libvirt and qemu-kvm on your system:

   • For Ubuntu-18.10

     $ sudo apt install qemu-kvm libvirt-daemon libvirt-daemon-system

   • For older Ubuntu versions

     $ sudo apt install libvirt-bin qemu-kvm

1. Add yourself to the libvirt(d) group:

   • For Ubuntu-18.10

     $ sudo usermod -a -G libvirt $(whoami)

   • For older Ubuntu versions

     $ sudo usermod -a -G libvirtd $(whoami)

1. Update your current session to apply the group change:

   • For Ubuntu-18.10

     $ newgrp libvirt

   • For older Ubuntu versions

     $ newgrp libvirtd

1. As root, install the KVM driver binary and make it executable as follows:

   • For Ubuntu-16.04 and higher

     # curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-ubuntu16.04 -o /usr/local/bin/docker-machine-driver-kvm
     # chmod +x /usr/local/bin/docker-machine-driver-kvm

   • For Ubuntu-14.04

     # curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-ubuntu14.04 -o /usr/local/bin/docker-machine-driver-kvm
     # chmod +x /usr/local/bin/docker-machine-driver-kvm

On Fedora

1. Install libvirt and qemu-kvm on your system:

   $ sudo dnf install libvirt qemu-kvm

2. Add yourself to the libvirt group:

   $ sudo usermod -a -G libvirt $(whoami)

3. Update your current session to apply the group change:

   $ newgrp libvirt

4. As root, install the KVM driver binary and make it executable as follows:

   # curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-centos7 -o /usr/local/bin/docker-machine-driver-kvm
   # chmod +x /usr/local/bin/docker-machine-driver-kvm

On Arch Linux

1. Install libvirt, qemu, dnsmasq and ebtables on your system:

   $ sudo pacman -S libvirt qemu dnsmasq ebtables

2. Add yourself to the kvm and libvirt groups:

   $ sudo usermod -a -G kvm,libvirt $(whoami)

3. Update the libvirt configuration in /etc/libvirt/qemu.conf as follows:

   $ sudo sed -ri 's/.?group\s?=\s?".+"/group = "kvm"/1' /etc/libvirt/qemu.conf

4. Update your current session to apply the group change:

   $ newgrp libvirt

5. As root, install the KVM driver binary and make it executable as follows:

   # curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-centos7 -o /usr/local/bin/docker-machine-driver-kvm
   # chmod +x /usr/local/bin/docker-machine-driver-kvm

Start libvirtd service

1. Check the status of libvirtd:

$ systemctl is-active libvirtd

1. If libvirtd is not active, start the libvirtd service:

$ sudo systemctl start libvirtd

Configure libvirt networking

Some distributions set up the default libvirt network for you, while on others this might have to be done manually.

1. Check your network status:

   $ sudo virsh net-list --all
   Name                 State      Autostart     Persistent
   ---------------------------------------------------------
   default              active     yes           yes

   If your output looks like the above then you’re done. However, if State is not active or Autostart is not yes you’ll need to follow the steps below.

2. Start the default libvirt network:

   $ sudo virsh net-start default

3. Now mark the default network as autostart:

   $ sudo virsh net-autostart default

Next Steps

Proceed to Installing Minishift once your hypervisor has been installed and configured.

macOS

Setting Up the xhyve Driver

Minishift is currently tested against docker-machine-driver-xhyve version 0.3.3.

Homebrew Install

Use the following command to install the latest version of the driver with Homebrew:

$ brew install docker-machine-driver-xhyve

Once installed, enable root access for the docker-machine-driver-xhyve binary and add it to the default wheel group:

$ sudo chown root:wheel $(brew --prefix)/opt/docker-machine-driver-xhyve/bin/docker-machine-driver-xhyve

Set the owner User ID (SUID) for the binary as follows:

$ sudo chmod u+s $(brew --prefix)/opt/docker-machine-driver-xhyve/bin/docker-machine-driver-xhyve

You can verify the existing version of the xhyve driver on your system using brew info as follows:

$ brew info --installed docker-machine-driver-xhyve
docker-machine-driver-xhyve: stable 0.3.3 (bottled), HEAD
Docker Machine driver for xhyve
https://github.com/zchee/docker-machine-driver-xhyve
/usr/local/Cellar/docker-machine-driver-xhyve/0.3.3 (3 files, 10.3MB) *
  Poured from bottle on 2017-08-18 at 14:46:20
From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/docker-machine-driver-xhyve.rb

For more information, see the GitHub documentation for the xhyve driver.

Manual Install

To manually install the xhyve driver, you need to download and install the docker-machine-driver-xhyve binary and place it in a directory which is on your PATH environment variable. The directory /usr/local/bin is recommended, as it is the default installation directory for Docker Machine binaries.

The following steps explain the installation of the docker-machine-driver-xhyve binary to the /usr/local/bin/ directory:

1. Download the docker-machine-driver-xhyve binary using:

   $ sudo curl -L  https://github.com/zchee/docker-machine-driver-xhyve/releases/download/v0.3.3/docker-machine-driver-xhyve -o /usr/local/bin/docker-machine-driver-xhyve

2. Enable root access for the docker-machine-driver-xhyve binary and add it to the default wheel group:

   $ sudo chown root:wheel /usr/local/bin/docker-machine-driver-xhyve

3. Set the owner User ID (SUID) for the binary as follows:

   $ sudo chmod u+s,+x /usr/local/bin/docker-machine-driver-xhyve

$ go get -u -d github.com/zchee/docker-machine-driver-xhyve
$ cd $GOPATH/src/github.com/zchee/docker-machine-driver-xhyve
# Install docker-machine-driver-xhyve binary into /usr/local/bin
$ make install
# docker-machine-driver-xhyve need root owner and uid
$ sudo chown root:wheel /usr/local/bin/docker-machine-driver-xhyve
$ sudo chmod u+s /usr/local/bin/docker-machine-driver-xhyve

Next Steps

Proceed to Installing Minishift once your hypervisor has been installed and configured.

On macOS, you may also install Minishift via Homebrew.

Setting Up the hyperkit Driver

Minishift is currently tested against docker-machine-driver-hyperkit version 1.0.0.

Using hyperkit requires having both the hyperkit driver and docker-machine-driver-hyperkit installed

Installing hyperkit

• If you have Docker Desktop for macOS installed, hyperkit is already installed.

• If you use Homebrew you can install the latest version of hyperkit:

$ brew install hyperkit

Installing docker-machine-driver-hyperkit

• If you use Homebrew you can install the latest version of docker-machine-driver-hyperkit:

$ brew install docker-machine-driver-hyperkit

• Alternatively, you can download and install the docker-machine-driver-hyperkit binary and place it in a directory which is on your PATH environment variable. The directory /usr/local/bin is a good choice, since it is the default installation directory for Docker Machine binaries.

The following steps explain the installation of the docker-machine-driver-hyperkit binary to the /usr/local/bin/ directory:

1. Download the docker-machine-driver-hyperkit binary using:

   $ sudo curl -L  https://github.com/machine-drivers/docker-machine-driver-hyperkit/releases/download/v1.0.0/docker-machine-driver-hyperkit -o /usr/local/bin/docker-machine-driver-hyperkit

2. Enable root access for the docker-machine-driver-hyperkit binary and add it to the default wheel group:

   $ sudo chown root:wheel /usr/local/bin/docker-machine-driver-hyperkit

3. Set owner User ID (SUID) for the binary as follows:

   $ sudo chmod u+s,+x /usr/local/bin/docker-machine-driver-hyperkit

$ go get -u -d github.com/machine-drivers/docker-machine-driver-hyperkit
$ cd $GOPATH/src/github.com/machine-drivers/docker-machine-driver-hyperkit
# Install docker-machine-driver-hyperkit binary into /usr/local/bin
$ make build

Next Steps

Proceed to Installing Minishift once your hypervisor has been installed and configured.

On macOS, you may also install Minishift via Homebrew.

Windows

Setting Up the Hyper-V Driver

To use Minishift with Hyper-V:

1. Install Hyper-V.

2. Add the user to the local Hyper-V Administrators group.

   This is required to allow the user to create and delete virtual machines with the Hyper-V Management API. For more information, see Hyper-V commands must be run as an Administrator.

3. Add an External Virtual Switch.

4. Verify that you pair the virtual switch with a network card (wired or wireless) that is connected to the network.

5. Use the configuration option hyperv-virtual-switch or startup flag --hyperv-virtual-switch to set the name of the external virtual switch you want to use for Minishift.

   For example, on PowerShell use

   PS> minishift config set hyperv-virtual-switch "External (Wireless)"

   or

   PS> minishift start --hyperv-virtual-switch "External (Wireless)"

   The name of the virtual switch is case sensitive. The use of the environment variable HYPERV_VIRTUAL_SWITCH has been deprecated. Instead MINISHIFT_HYPERV_VIRTUAL_SWITCH can be used as a configuration option, although this is not recommended as environment variables on Windows do not support non-ASCII characters.

Next Steps

Proceed to Installing Minishift once your hypervisor has been installed and configured.

Setting Up Minishift to Use VirtualBox

VirtualBox must be manually installed in order to use the embedded VirtualBox drivers. VirtualBox version 5.1.12 or later is required. Ensure that you download and install VirtualBox before using the embedded drivers.

VirtualBox must be identified to Minishift through either the --vm-driver virtualbox flag or persistant configuration options.

Use VirtualBox Temporarily

The --vm-driver virtualbox flag will need to be given on the command line each time the minishift start command is run. For example:

$ minishift start --vm-driver virtualbox

Use VirtualBox Permanently

Setting the vm-driver option as a persistent configuration option allows you to run minishift start without explicitly passing the --vm-driver virtualbox flag each time. You may set the vm-driver persistent configuration option as follows:

$ minishift config set vm-driver virtualbox

Next Steps

Proceed to Installing Minishift once your hypervisor has been installed and configured.