Starting Container Development Kit requires a valid Red Hat Enterprise Linux license, because Container Development Kit includes an KVM virtual machine image with Red Hat Enterprise Linux installed.

At startup, minishift registers the Red Hat Enterprise Linux license, and holds it until it is released at shutdown. The login information for that Red Hat Enterprise Linux license can be provided either on the command line or as environment variables.

To start Container Development Kit using environment variables, first set MINISHIFT_USERNAME and MINISHIFT_PASSWORD:

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

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>

The minishift start command downloads any required OpenShift functionality, starts OpenShift services, and prints some helpful information about 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. Start by running the minishift start command.

~]$ minishift start
Starting local OpenShift cluster using 'kvm' hypervisor...
...
   OpenShift server started.
   The server is accessible via web console at:
       https://192.168.99.128:8443

   You are logged in as:
       User:     developer
       Password: developer

   To login as administrator:
       oc login -u system:admin

Use minishift oc-env to display the command you need to type into your shell in order to add the oc binary to your PATH. The output of oc-env may differ, depending on OS and shell type.

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

For more information about interacting with OpenShift with the command-line interface and the web console, see the Chapter 7, Interacting with OpenShift section.

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.

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:

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

~]$ minishift config view
- memory: 4096

~]$ minishift config get memory
4096

~]$ minishift config unset memory

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

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.

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.

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

OpenShift provides various sample applications, such as templates, builder applications, and quickstarts. The following steps describe how to deploy a sample Node.js application from the command-line.

For more information about creating applications in OpenShift, see Creating New Applications in the OpenShift documentation.

Deploying a WildFly application requires a few steps, so here’s an example of deploying a new app:

Minishift allows to configure the vanilla OpenShift setup provided by cluster up with an add-on mechanism.

Add-ons are directories that contain one or more text files with the addon extension. The directory can also have other resource files such as JSON template files. However, only one addon file is allowed.

# Name: anyuid                                                                          1
# Description: Allows authenticated users to run images under a non pre-allocated UID   2

oc adm policy add-scc-to-group anyuid system:authenticated                              3

Enabled add-ons are applied during minishift start, immediately after the initial cluster provisioning successfully completes.

~]$ openshift admin ca create-server-cert \ --signer-cert=/var/lib/origin/openshift.local.config/master/ca.crt \ --signer-key=/var/lib/origin/openshift.local.config/master/ca.key \ --signer-serial=/var/lib/origin/openshift.local.config/master/ca.serial.txt \ --hostnames='docker-registry-default.#{routing-suffix},docker-registry.default.svc.cluster.local,172.30.1.1' \ --cert=/etc/secrets/registry.crt \ --key=/etc/secrets/registry.key

~]$ minishift addons install --defaults

~]$ minishift addons list --verbose=true

Add-ons are enabled with the minishift addons enable command and disabled with the minishift addons disable command.

The following examples show how to enable and disable the anyuid add-on.

~]$ minishift addons enable anyuid

~]$ minishift addons disable anyuid

~]$ minishift addons enable registry --priority=5

~]$ minishift addons list
- anyuid         : enabled    P(0)
- registry       : enabled    P(5)
- eap            : enabled    P(10)

# Name: admin-role
# Description: Gives the developer user cluster-admin privileges

oc adm policy add-role-to-user cluster-admin developer

$ minishift addons install <ADDON_DIR_PATH>

Host folders are directories on the host which are shared between the host and the Minishift VM. They allow for a two way file synchronization between host and VM. The following sections discuss the various types of host folders, driver provided host folders, as well as the Minishift hostfolder command.

Some drivers mount a default host folder into the VM in order to share files between the VM and the host. These folders are currently not configurable and differ for each driver and OS.

Minishift provides the hostfolder command to list, add, mount, unmount and remove host folders. In contrast to the driver provided host folders, the hostfolder command allows you to mount multiple shared folders onto custom specified mount points.

At the moment only CIFS is supported as host folder type. Support for SSHFS based host folders is in progress (see GitHub issue #317).

If you want to use SSHFS now, refer to Section 6.10, “SSHFS Host Folders” for manual instructions.

The following sections describe the prerequisite for using the hostfolder command, as well as the various sub-commands it provides.

To use the hostfolder command, you need to be able to share directories using CIFS. On Windows CIFS is the default technology for sharing directories. For example, on Microsoft Windows 10 the C:\Users folder is shared by default and can be accessed by locally-authenticated users.

It is also possible to use CIFS on OS X and Linux. On the former you can enable CIFS based shares under System Preferences > Sharing. Refer to How to connect with File Sharing on your Mac for detailed setup instructions.

On Red Hat Enterprise Linux, install samba with yum:

~]$ yum install "samba-*"

The hostfolder list command gives you an overview of the defined host folders, their name, mount point, remote path and whether they are currently mounted. An example output could look like:

~]$ minishift hostfolder list
Name        Mountpoint            Remote path              Mounted
myshare     /mnt/sda1/myshare     //192.168.1.82/MYSHARE   N

In this example, there is a host folder with the name myshare which mounts //192.168.1.82/MYSHARE onto /mnt/sda1/myshare in the Minishift VM. The share is currently not mounted.

The hostfolder add command allows you to define a new host folder. This in an interactive process which queries the relevant details for a host folder based on CIFS.

~]$ minishift hostfolder add myshare 1
UNC path: //192.168.99.1/MYSHARE   2
Mountpoint [/mnt/sda1/myshare]:    3
Username: john                     4
Password: [HIDDEN]                 5
Domain:                            6
Added: myshare

Once you have added your host folder definitions, the hostfolder mount command allows you to mount a host folder by its name:

~]$ minishift hostfolder mount myshare
Mounting 'myshare': '//192.168.99.1/MYSHARE' as '/mnt/sda1/myshare' ... OK

You can verify that the host folder is mounted by running:

~]$ minishift hostfolder list
Name       Mountpoint          Remote path              Mounted
myshare    /mnt/sda1/myshare   //192.168.99.1/MYSHARE   Y

Alternatively, you can list the actual content of the mounted host folder:

~]$ minishift ssh "ls -al /mnt/sda1/myshare"

~]$ minishift config set hostfolders-automount true

In contrast to the hostfolder add command, hostfolder umount can be used to unmount a host folder:

~]$ minishift hostfolder umount myshare
Unmounting 'myshare' ... OK

~]$ minishift hostfolder list
Name       Mountpoint          Remote path              Mounted
myshare    /mnt/sda1/myshare   //192.168.99.1/MYSHARE   N

The hostfolder remove command finally enabled you to remove a host folder definition:

~]$ minishift hostfolder list
Name        Mountpoint            Remote path              Mounted
myshare     /mnt/sda1/myshare     //192.168.1.82/MYSHARE   N

~]$ minishift hostfolder remove myshare
Removed: myshare

~]$ minishift hostfolder list
No host folders defined

You can also use SSHFS-based host folders provided you have an SSH daemon running on your host. Normally, this prerequisite is met by default on Red Hat Enterprise Linux and macOS.

To use the SSH server on macOS, make sure that Remote Login is enabled in System Preferences > Sharing.

On Microsoft Windows you can install OpenSSH for Windows.

The following steps demonstrate how to mount host folders with SSHFS.

Minishift creates a virtual machine (VM) and provisions a local, single-node OpenShift cluster in this VM. The following sections describe how Minishift can assist you in interacting with and configuring your local OpenShift instance.

For details about managing the Minishift VM, see the Managing Minishift section.

The minishift start command creates an OpenShift instance using the cluster up approach.

For this purpose it copies the oc binary onto your host. You will find it under ~/.minishift/cache/oc/3.5/oc, provided you use Minishift’s default version of OpenShift.

You can add this binary to your PATH using minishift oc-env which displays the command you need to type into your shell. The output of oc-env will differ depending on OS and shell type.

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

As part of the minishift start command there is also a minishift oc context created. This context contains the configuration to communicate with your OpenShift cluster.

Minishift activates this context automatically, but if you need to switch back to it after for example, logging into another OpenShift instance, you can run:

~]$ oc config use-context minishift

For an introduction to oc usage, refer to the Get Started with the CLI topic in the OpenShift documentation.

By default, cluster up uses AllowAllPasswordIdentityProvider to authenticate against the local cluster. This means any non-empty user name and password can be used to login to the local cluster. The recommended user name and password combination is developer/developer, because it already has a default project myproject and also can impersonate the administrator user. This allows to run administrator commands using the --as system:admin parameter.

To login as administrator, use the system account:

~]$ oc login -u system:admin

In this case, client certificates are used. The certificates are stored in ~/.kube/config. The cluster up command installs the appropriate certificates as a part of the bootstrap.

To view the currently available login contexts, run:

~]$ oc config view

To access the OpenShift console, you can run this command in a shell after starting Minishift to get the URL of the Web console:

~]$ minishift console --url

Alternatively, after starting Minishift, you can use the following command to directly open the console in a browser:

~]$ minishift console

To access a service exposed with a node port, run this command in a shell after starting Minishift to get the address:

~]$ minishift openshift service [-n <NAMESPACE>] [--url] <NAME>

To access OpenShift logs, run the logs command after starting Minishift:

~]$ minishift logs

While OpenShift is running, you can view and change the master or the node configuration of your cluster.

To view the current OpenShift master configuration master-config.yaml, run the following command:

~]$ minishift openshift config view

To show the node configuration instead of the master configuration, specify the target flag.

In this example, you configure cross-origin resource sharing (CORS) by updating the OpenShift master configuration to allow additional IP addresses to request resources.

By default, OpenShift only allows cross-origin resource requests from the IP address of the cluster or from localhost. This setting is stored in the corsAllowedOrigins property of the master configuration file master-config.yaml.

To change the property value and allow cross-origin requests from all domains, run the following command:

~]$  minishift openshift config set --patch '{"corsAllowedOrigins": ["."]}'*

$  .\minishift.exe --% openshift config set --patch "{\"routingConfig\": {\"subdomain\": \"192.168.99.101.nip.io\"}}"

$ .\minishift.exe openshift config set --patch "{\"routingConfig\": {\"subdomain\": \"192.168.99.101.nip.io\"}}"

~]$ minishift openshift config set --patch '{"routingConfig": {"subdomain": "<IP-ADDRESS>.xip.io"}}'

OpenShift provides an integrated Docker registry which can be used for development as well. Images present in the registry can directly be used for applications, speeding up the local development work-flow. Refer to Section 9.3, “Deploying an Application with Docker” to know more.

~]$ docker login -u developer -p $(oc whoami -t) $(minishift openshift registry)

The following example shows how to deploy an OpenShift application directly from a locally built docker image. In this example, the OpenShift project myproject is used, as it is automatically created by minishift start.

This section contains solutions to common problems that you might encounter while using Minishift.

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 Minishift 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.

~]$ rm -rf ~/.minishift/machines

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

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

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

In case all of this fails, you may want to uninstall Minishift and do a fresh install of Minishift.

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 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 Microsoft 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.

If you run Minishift with Hyper-V on Microsoft Windows as a normal user or as a user with Administrator privileges, you will encounter the following error:

Error starting the VM: Error creating the VM. Error with pre-create check: "Hyper-V commands must be run as an Administrator".

Workaround: To overcome this error you can either add yourself to the Hyper-V Administrators group, which is recommended, or run the shell in an elevated mode.

If use PowerShell, you can add yourself to the Hyper-V Administrators group as follows:

You can also use the GUI to add yourself to the Hyper-V Administrators group as follows:

Now you can run the Hyper-V commands as a normal user.

For more options for Hyper-V see creating Hyper-V administrators local group.