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:

Setting Up the KVM Driver

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

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

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

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

On Debian/Ubuntu

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

    $ sudo apt install libvirt-bin qemu-kvm
  2. Add yourself to the libvirtd group:

    $ sudo usermod -a -G libvirtd <username>
  3. Update your current session to apply the group change:

    $ newgrp libvirtd

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 <username>
  3. Update your current session to apply the group change:

    $ newgrp libvirt

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 <username>
  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

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.

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

The downloaded docker-machine-driver-xhyve binary is compiled against a specific version of macOS. The driver may 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/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

For more information, see the xhyve 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.

Setting Up the hyperkit Driver

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

To install the hyperkit driver, you need to 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 link: 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.

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. Set the environment variable HYPERV_VIRTUAL_SWITCH to the name of the external virtual switch you want to use for Minishift.

    For example, on Command Prompt use:

    C:\> set HYPERV_VIRTUAL_SWITCH=External (Wireless)

    Note that using quotes in Command Prompt results in the following error:

    C:\> set HYPERV_VIRTUAL_SWITCH="External (Wireless)"
    Error creating the VM. Error with pre-create check: "vswitch \"\\\"External (Wireless)\\\"\" not found"

    PowerShell, however, requires the quotes:

    PS> $env:HYPERV_VIRTUAL_SWITCH="External (Wireless)"

    Using set in Command Prompt or $env in PowerShell will only affect the currently running shell session. You may use the setx utility to persist this environment variable across shell instances and system restarts. Quotes must be used with setx for both Command Prompt and PowerShell. For example:

    C:\> setx HYPERV_VIRTUAL_SWITCH "External (Wireless)"

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.