Red Hat Training

A Red Hat training course is available for Red Hat Container Development Kit

Chapter 3. Minishift

When you use Minishift, you interact with two components:

  • a virtual machine (VM) created by Minishift
  • the OpenShift cluster provisioned by Minishift within the VM

3.1. Minishift Commands

The following sections contain information about managing the Minishift VM. For details about using Minishift to manage your local OpenShift cluster, see the Chapter 7, Interacting with OpenShift section.

3.1.1. minishift start

The minishift start command creates and configures the Minishift VM and provisions a local, single-node OpenShift instance within the VM.

The command also copies the oc binary to your host so that you can interact with through the oc command line tool or through the Web console, which can be accessed through the URL provided in the output of the minishift start command.

3.1.2. minishift stop

The minishift stop command stops your OpenShift cluster and shuts down the Minishift VM, but preserves the OpenShift cluster state.

Starting Minishift again will restore the OpenShift cluster, allowing you to continue working from the last session. However, you must enter the same parameters that you used in the original start command.

3.1.3. minishift delete

The minishift delete command deletes the OpenShift cluster, and also shuts down and deletes the {mshift VM}. No data or state are preserved.

3.2. Runtime Options

The runtime behavior of Minishift can be controlled through flags, environment variables, and persistent configuration options.

The following precedence order is applied to control the behavior of Minishift. Each action in the following list takes precedence over the action below it:

  1. Use command-line flags as specified in the Section 3.2.1, “Flags” section.
  2. Set environment variables as described in the Section 3.2.2, “Environment Variables” section.
  3. Use persistent configuration options as described in the Section 3.2.3, “Persistent Configuration” section.
  4. Accept the default value as defined by Minishift.

3.2.1. Flags

You can use command line flags with Minishift to specify options and direct its behavior. This has the highest precedence. Almost all commands have flags, although different commands might have different flags. Some of the commonly used command line flags of the minishift start command are cpus, memory or vm-driver.

3.2.2. Environment Variables

Minishift allows you to specify command-line flags you commonly use through environment variables. To do so, apply the following rules to the flag you want to set as an environment variable.

  1. Apply MINISHIFT_ as a prefix to the flag you want to set as an environment variable. For example, the vm-driver flag of the minishift start command becomes MINISHIFT_vm-driver.
  2. Use uppercase characters for the flag, so MINISHIFT_vm-driver in the above example becomes MINISHIFT_VM-DRIVER.
  3. Replace - with _, so MINISHIFT_VM-DRIVER becomes MINISHIFT_VM_DRIVER.

Environment variables can be used to replace any option of any Minishift command. A common example is the URL of the ISO to be used. Usually, you specify it with the iso-url flag of the minishift start command. Applying the above rules, you can also specify this URL by setting the environment variable as MINISHIFT_ISO_URL.

Note

By default, Minishift places all runtime state into ~/.minishift. You can also use the MINISHIFT_HOME environment variable, to choose a different home directory for Minishift. This environment variable is currently experimental and semantics might change in future releases.

3.2.3. Persistent Configuration

Using persistent configuration allows you to control the Minishift behavior without specifying actual command line flags, similar to the way you use Section 3.2.2, “Environment Variables”.

Minishift maintains a configuration file in $MINISHIFT_HOME/config/config.json. This file can be used to set commonly-used command-line flags persistently.

Note

Persistent configuration can only be applied to the set of supported configuration options that are listed in the synopsis of the minishift config sub-command, unlike environment variables that can be used to replace any option of any command.

3.2.3.1. Setting Persistent Configuration Values

The easiest way to change a persistent configuration option is with the config set sub-command. For example: 

# Set default memory 4096 MB
~]$ minishift config set memory 4096

To view all persistent configuration values, you can use the view sub-command: 

~]$ minishift config view
- memory: 4096

Alternatively, you can display a single value with the get sub-command: 

~]$ minishift config get memory
4096

3.2.3.2. Unsetting persistent configuration values

To remove a persistent configuration option, you can use the unset sub-command. For example: 

~]$ minishift config unset memory

3.2.4. Driver Specific Environment Variables

You can also specify driver specific environment variables. Each docker-machine driver supports its own set of options and variables. A good starting point is the official docker-machine driver documentation. xhyve and KVM documentation is available under their respective GitHub repository docker-machine-driver-xhyve and docker-machine-kvm.

To use driver specific options make sure to export the variable as defined in its driver documentation prior to running minishift start. For example, xhyve’s experimental NFS sharing can be enabled by executing: 

~]$ export XHYVE_EXPERIMENTAL_NFS_SHARE=true
~]$ minishift start --vm-driver xhyve
Caution

Driver specific options might overlap with values specified using Minishift specific flags and environment variables. Examples are boot2docker URL, memory size, cpu count, etc. In this case driver specific environment variables will override Minishift specific settings.

3.3. Persistent Volumes

As part of provisioning with cluster up, the Section 7.2, “Using the OpenShift Client Binary (oc)” creates persistent volumes for your OpenShift cluster. This allows applications to make persistent volumes claims. The location of the persistent data is determined via the host-pv-dir flag of the start command and defaults to /var/lib/minishift/openshift.local.pv on the Minishift VM.

3.4. HTTP/HTTPS Proxies

If you are behind a HTTP/HTTPS proxy, you need to supply proxy options to allow Docker and OpenShift to work properly. To do this, pass the required flags during minishift start.

For example: 

~]$ minishift start --http-proxy http://<YOURPROXY>:<PORT> --https-proxy https://<YOURPROXY>:<PORT>

In an authenticated proxy environment, the proxy_user and proxy_password must be a part of proxy URI. 

~]$ minishift start --http-proxy http://<proxy_username>:<proxy_password>@<YOURPROXY>:<PORT> \ --https-proxy https://<proxy_username>:<proxy_password>@<YOURPROXY>:<PORT>

You can also use the --no-proxy flag to specify a comma-separated list of hosts that should not be proxied. For a list of all available options, see the synopsis of the start command.

Using the proxy options will transparently configure the Docker daemon and OpenShift to use the specified proxies.

Note

Use the minishift start --ocp-tag flag to request a specific version of OpenShift Container Platform. You can list all Minishift-compatible OpenShift Container Platform versions with the minishift openshift version list command. By default, Red Hat Container Development Kit 3.0 uses OpenShift Container Platform v3.5.5.8.

3.5. Networking

The Minishift VM is exposed to the host system with a host-only IP address that can be obtained with the minishift ip command.