1. Documentation
×

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:

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

  2. 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)

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

    • For Ubuntu-18.10

      $ newgrp libvirt

    • For older Ubuntu versions

      $ newgrp libvirtd

  4. 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 hyperkit Driver

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

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

Installing 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

The downloaded docker-machine-driver-hyperkit binary is compiled against a specific version of macOS. It is possible that the driver will fail to work after a macOS version upgrade. In this case you can try to compile the driver from source:

$ 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

For more information, see the hyperkit driver documentation on GitHub.

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

The vm-driver persistent configuration option must be supplied before minishift start has been run. If you have already run minishift start, ensure that you run minishift delete, set the configuration with minishift config set vm-driver virtualbox, then run minishift start in order to make use of the VirtualBox driver.

Next Steps

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