Overview

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

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

Minishift Life-cycle

Minishift start Command

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

The command also copies the oc binary to your host so that you can interact with OpenShift 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.

Minishift stop Command

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.

Efforts to further refine this experience are in progress. For details, see the GitHub issue #179.

Minishift delete Command

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

Choosing the ISO Image

When you start Minishift, it downloads a live ISO image that the hypervisor uses to provision the Minishift VM.

The following ISO images are available:

  • Minishift Boot2Docker (Default). This ISO image is based on Boot2Docker, which is a lightweight Linux distribution customized to run Docker containers. The image size is small and optimized for development but not for production.

  • Minishift CentOS. This ISO image is based on CentOS, which is an enterprise-ready Linux distribution that more closely resembles a production environment. The image size is larger than the Boot2Docker ISO image.

By default, Minishift uses the Minishift Boot2Docker ISO image. To choose the Minishift CentOS ISO image instead, you can do one of the following:

  • Use the centos alias to download and use the latest CentOS ISO:

    $ minishift start --iso-url centos
  • Specify explicitly the download URL of the Minishift CentOS ISO image. For example:

    $ minishift start --iso-url https://github.com/minishift/minishift-centos-iso/releases/download/v1.2.0/minishift-centos7.iso
  • Manually download the Minishift CentSO ISO image from the releases page and enter the file URI to the image:

    $ minishift start --iso-url file:///<path_to_ISO_image>
You cannot run Minishift with both ISO images concurrently. To switch between ISO images, delete the Minishift instance and start a new instance with the ISO image that you want to use.

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 Flags section.

  2. Set environment variables as described in the Environment Variables section.

  3. Use persistent configuration options as described in the Persistent Configuration section.

  4. Accept the default value as defined by Minishift.

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.

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.

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

Persistent Configuration

Using persistent configuration allows you to control the Minishift behavior without specifying actual command line flags, similar to the way you use 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.

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. This is different from environment variables, which can be used to replace any option of any command.

Setting Persistent Configuration Values

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

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

Flags which can be used multiple times per command invocation, like docker-env or insecure-registry, need to be comma-separated when used with the config set command. For example, from the CLI, you can use insecure-registry like this:

$ minishift start --insecure-registry hub.foo.com --insecure-registry hub.bar.com

If you want to configure the same registries in the persistent configuration, you would run:

$ minishift config set insecure-registry hub.foo.com,hub.bar.com

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

$ minishift config view
- memory: 4096

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

$ minishift config get memory
4096

Unsetting Persistent Configuration Values

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

$ minishift config unset memory

Driver-Specific Environment Variables

You can also set 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 before running minishift start. For example, the xhyve experimental NFS sharing can be enabled by executing:

$ export XHYVE_EXPERIMENTAL_NFS_SHARE=true
$ minishift start --vm-driver xhyve
Driver-specific options might overlap with values specified using Minishift-specific flags and environment variables. Examples are boot2docker URL, memory size, cpu count, and so on. In this case, driver-specific environment variables will override Minishift-specific settings.

Caching OpenShift images (experimental)

To speed up provisioning of the OpenShift cluster and to minimize network traffic, the core OpenShift images can be cached on the host. This feature is considered experimental and needs to be explicitly enabled using the minishift config set command:

$ minishift config set image-caching true

Once enabled, caching occurs transparently, in a background process, the first time you use the minishift start command. Once the images are cached under $MINISHIFT_HOME/cache/images, successive Minishift VM creations will use these cached images.

Each time an image exporting background process runs, a log file is generated under $MINISHIFT_HOME/logs which can be used to verify the progress of the export.

You can disable the caching of the OpenShift images by setting image-caching to false or removing the setting altogether using minishift config unset:

$ minishift config unset image-caching
Image caching is considered experimental and its semantics and API is subject to change. The aim is to allow caching of arbitrary images, as well as using a better format for storing the images on the host. You can track the progress on this feature on the GitHub issue #952.

Persistent Volumes

As part of the OpenShift cluster provisioning, 100 persistent volumes are created for your OpenShift cluster. This allows applications to make persistent volumes claims. The location of the persistent data is determined in the host-pv-dir flag of the minishift start command and defaults to /var/lib/minishift/openshift.local.pv on the Minishift VM.

HTTP/HTTPS Proxies

If you are behind an 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.

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

  • minishift start honors the environment variables HTTP_PROXY, HTTPS_PROXY and NO_PROXY. If these variables are set, they are implicitly used during minishift start unless explicitly overridden by the corresponding command line flags.

  • Using the proxy options requires that you run OpenShift version 1.5.0 or later. Use the openshift-version option to request a specific version of OpenShift. You can list all Minishift-compatible OpenShift versions with the minishift openshift version list command.

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.

Connecting to the Minishift VM with SSH

You can use the minishift ssh command to interact with the Minishift VM.

You can run minishift ssh without a sub-command to open an interactive shell and run commands on the Minishift VM in the same way that you run commands interactively on any remote machine using SSH.

You can also run minishift ssh with a sub-command to send the sub-command directly to the Minishift VM and return the result to your local shell. For example:

$ minishift ssh -- docker ps
CONTAINER    IMAGE                   COMMAND                CREATED        STATUS        NAMES
71fe8ff16548 openshift/origin:v1.5.1 "/usr/bin/openshift s" 4 minutes ago  Up 4 minutes  origin

Experimental Features

If you want to get early access to some upcoming features and experiment, you can enable some of those in Minishift.

You do this by setting the environment variable MINISHIFT_ENABLE_EXPERIMENTAL, which makes additional flags available:

$ export MINISHIFT_ENABLE_EXPERIMENTAL=y

Experimental features are not officially supported, and might break or result in unexpected behavior. To share your feedback on these features, you are welcome to contact the Minishift community.

Enabling experimental oc cluster up flags in minishift start

By default, Minishift does not expose all oc cluster up flags in the Minishift CLI.

You can set the MINISHIFT_ENABLE_EXPERIMENTAL environment variable to enable the following options for the minishift start command:

service-catalog

Enables provisioning the OpenShift service catalog.

extra-clusterup-flags

Enables passing flags that are not directly exposed in the Minishift CLI directly to oc cluster up.