Installation Guide

This document is based on the documentation for Minishift that can be found at minishift.io, and considers that documentation to be the upstream documentation. However, this documentation has a focus on functionality in Red Hat Container Development Kit. Some upstream features that are not specifically relevant to Container Development Kit users has been modified or removed.

Once the Container Development Environment from Container Development Kit is running on your system, you can begin exploring the contents. Some services and tools run automatically when you boot the virtual machine while others require configuration. Here is a list of some of those features:

Red Hat Container Development Kit was designed to let you do your container development using the same computer on which you do your other work. A hypervisor is required in each case, and the Red Hat Enterprise Linux virtual machine will use that hypervisor.

Container Development Kit can be installed on the following systems:

See the Container Development Kit installation procedure for each system for more detailed hardware and software requirements.

Container Development Kit is available from the Red Hat Customer Portal to anyone with a valid Red Hat Enterprise Linux Developer Subscription. Joining the Red Hat Developers program also provides a path to getting Container Development Kit.

This guide provides the following instructions for installing Container Development Kit to begin developing containerized applications:

Regardless of which platform you choose as the workstation for using Container Development Kit, you will use Minishift to start and manage it.

Minishift includes a virtual machine, with Red Hat Enterprise Linux installed on that virtual machine.

Now that you understand the basics of what is inside Container Development Kit, choose from one of the next chapters to learn how to obtain Container Development Kit and install it on a Microsoft Windows, macOS, or Red Hat Enterprise Linux system.

Minishift uses Docker Machine and its driver plugin architecture to provide a consistent way to manage the OpenShift VM. Minishift embeds VirtualBox and VMware Fusion drivers so no additional steps are required to use them.

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

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

Install and execute 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
~]$ sudo chmod +x /usr/local/bin/docker-machine-driver-kvm

For more information, see the GitHub documentation of the docker machine KVM driver.

~]$ sudo yum install libvirt qemu-kvm

~]$ sudo usermod -a -G libvirt <username>

~]$ newgrp libvirt

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

You can verify the installed version of the xhyve driver on your system before you install.

~]$ brew info --installed docker-machine-driver-xhyve
docker-machine-driver-xhyve: stable 0.3.1 (bottled), HEAD
Docker Machine driver for xhyve
https://github.com/zchee/docker-machine-driver-xhyve
/usr/local/Cellar/docker-machine-driver-xhyve/0.3.1 (3 files, 13.2M) *
  Poured from bottle on 2016-12-20 at 17:44:35
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.

~]$ 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

Check that the following requirements are met:

Container Development Kit requires a hypervisor to start the virtual machine on which the OpenShift cluster is provisioned. Make sure that the hypervisor of your choice is installed and enabled on your system before you start Container Development Kit.

Depending on your host OS, you have the choice of the following hypervisors:

Container Development Kit will be installed in the user’s personal directory. Virtualized boxes and configuration files will be stored under that directory.

Complete the following steps as a normal user (not root), to install Container Development Kit:

Red Hat Container Development Kit installation on Red Hat Enterprise Linux uses the native RPM technology provided by Red Hat Enterprise Linux. Installing Container Development Kit requires several steps:

~]$ minishift oc-env
export PATH="/Users/john/.minishift/cache/oc/v1.5.0:$PATH"
# Run this command to configure your shell:
# eval $(minishift oc-env)

~]$ oc config use-context minishift

Start Container Development Kit for the first time. You will need to set the environment variables MINISHIFT_USERNAME and MINISHIFT_PASSWORD to activate the Red Hat Enterprise Linux subscription used by your Minishift cluster. This will register the virtual machine that runs Red Hat Enterprise Linux, until it is released at shutdown. For further assistance in taking your first steps with Container Development Kit, see the Container Development Kit Getting Started Guide.

~]$ export MINISHIFT_USERNAME=<Red_Hat_username>
~]$ export MINISHIFT_PASSWORD=<Red_Hat_password>
~]$ minishift start

Instead of the environment variables MINISHIFT_USERNAME and MINISHIFT_PASSWORD, you may also specify the username and password on the command line:

~]$ minishift --username=<Red Hat username> --password=<Red Hat password> start

The start command should download any required OpenShift functionality, start OpenShift services, and print some helpful information about using the command line and web interfaces.

At this point, you should be able to use the tools minishift and oc to manage your Container Development Kit cluster.

If you want to work with the virtual machine offline, you must register it to activate a Red Hat Enterprise Linux first. Container Development Kit also provides the ability for the VM to remain registered, so that you can skip that step. Skipping registration is convenient for working offline.

First, login with minishift while online:

~]$ minishift --username=<Red Hat username> --password=<Red Hat password> start

Next, stop minishift with a --skip-registration option. This shuts down the VM without releasing the Red Hat Enterprise Linux subscription.

~]$ minishift stop --skip-unregistration

Disconnect or log out as needed. While you are offline, use the --skip-registration option to skip the attempt to register the Red Hat Enterprise Linux VM at boot. The Red Hat Enterprise Linux subscription is still active on the virtual machine, so you do not need to specify your username and password.

~]$ minishift start --skip-registration

Depending on your operating system and shell environment, certain special characters can trigger variable interpolation and therefore cause passwords to fail.

Workaround: When creating and entering passwords, wrap the string with single quotes in the following format: '<password>'

If you use virsh on KVM/libvirt to create snapshots in your development workflow, and then use minishift delete to delete the snapshots along with the VM, you might encounter the following error:

~]$ minishift delete
Deleting the {mshift} VM...
Error deleting the VM:  [Code-55] [Domain-10] Requested operation is not valid: cannot delete inactive domain with 4 snapshots

Cause: The snapshots are stored in ~/.minishift/machines, but the definitions are stored in var/lib/libvirt/qemu/snapshot/minishift.

Workaround: To delete the snapshots you need to perform the following steps.

It is recommended to avoid using metadata when you create snapshots. To make sure of this, you can specify the --no-metadata flag. For example:

~]$ sudo virsh snapshot-create-as --domain vm1 overlay1 --diskspec vda,file=/export/overlay1.qcow2 --disk-only --atomic --no-metadata

~]$ systemctl status libvirtd

If libvirtd is not running, start it and enable it to start on boot:

~]$ systemctl start libvirtd
~]$ systemctl enable libvirtd

The problem is likely that the virtlogd service is not running. You can check this with the following command:

~]$ systemctl status virtlogd

If virtlogd is not running, start it and enable it to start on boot:

~]$ systemctl start virtlogd
~]$ systemctl enable virtlogd

If you try minishift start and hit the above error, ensure that you use minishift delete to delete the VMs created earlier by you. However if this fails and you wish to completely clean up Minishift and start fresh do the following:

The problem is likely that the xhyve driver is not able to clean up vmnet when a VM is removed. vmnet.framework determines the IP address based on the following files:

Reset the minishift-specific IP database, make sure to remove the minishift entry section from the dhcpd_leases file, and reboot your system.

{
  ip_address=192.168.64.2
  hw_address=1,2:51:8:22:87:a6
  identifier=1,2:51:8:22:87:a6
  lease=0x585e6e70
  name=minishift
}

If you use Windows, make sure that you set the --vm-driver virtualbox flag in the minishift start command. Alternatively, the problem might be an outdated version of VirtualBox.

To avoid this issue, it is recommended to use VirtualBox 5.1.12 or later.