1. Documentation
×

Setting Up the Driver Plug-in

Overview

Minishift uses Docker Machine and its driver plug-in architecture to provide a consistent way to manage the OpenShift VM. Minishift embeds the VirtualBox driver plugin. No additional steps are required to use it.

However, other drivers require manual installation and setup that are described in the following sections.

KVM Driver

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

  1. Install the KVM binary as follows:

    $ sudo 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

  2. Make the binary executable as follows:

    $ sudo 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 (this may vary according to the Linux distribution) so that you do not need to use sudo:

    $ 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 so that you do not need to use sudo:

    $ 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 kvm and libvirt groups:

    $ sudo usemod -a -G kvm,libvirt <username>

  3. Update libvirt configuration in /etc/libvirt/qemu.conf:

    $ sudo sed -r 's/group=".+"/group="kvm"/1' /etc/libvirt/qemu.conf > /etc/libvirt/qemu.conf

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

    $ newgrp libvirt

xhyve Driver

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

Homebrew Install

You can verify the existing version of the xhyve driver on your system using:

$ 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

To install the latest version of the driver with brew:

$ brew install docker-machine-driver-xhyve

# docker-machine-driver-xhyve need root owner and uid
$ sudo chown root:wheel $(brew --prefix)/opt/docker-machine-driver-xhyve/bin/docker-machine-driver-xhyve
$ sudo chmod u+s $(brew --prefix)/opt/docker-machine-driver-xhyve/bin/docker-machine-driver-xhyve

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 most likely 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-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 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. 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/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.

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.

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

  4. 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"

    However, on PowerShell you need to use the quotes:

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