Getting Started Guide

The following section describes how to install CDK and the required dependencies.

These are the basic steps for setting up CDK on your personal system:

The setup procedure should be run as a regular user with permission to launch virtual machines. In the procedure, you will see how to assign that permission, along with ways to configure your hypervisor and command shell to start and effectively interact with CDK.

CDK requires a hypervisor to start the virtual machine on which the OpenShift cluster is provisioned. Verify that the hypervisor of your choice is installed and enabled on your system before you set up CDK. Once the hypervisor is up and running, additional setup is required for CDK to work with that hypervisor.

Depending on your host operating system, you have the choice of the following recommended native hypervisors:

Refer to the documentation for each hypervisor to determine the hardware and operating system versions needed to run that hypervisor.

Follow the appropriate procedure to set up the hypervisor for your particular operating system. CDK uses libmachine and its driver plug-in architecture to provide a consistent way to manage the CDK VM.

Some hypervisors require manual installation of the driver plug-in. CDK embeds the VirtualBox driver plug-in, so no additional steps are required to configure it. However, VirtualBox will need to be identified to CDK via the --vm-driver virtualbox flag or persistant configuration settings. See Setting Up CDK to Use VirtualBox for more information.

See the appropriate section for your hypervisor and operating system:

VirtualBox must be manually installed in order to use the embedded VirtualBox drivers. VirtualBox version 5.1.12 or later is required. Ensure that you download and install VirtualBox before using the embedded drivers.

VirtualBox must be identified to CDK through either the --vm-driver virtualbox flag or persistant configuration options.

$ minishift start --vm-driver virtualbox

$ minishift config set vm-driver virtualbox

This section contains a brief demo of CDK and of the provisioned OpenShift cluster. For details on the usage of CDK, see the Basic Usage section.

The interaction with OpenShift is with the command line tool oc which is copied to your host. For more information on how CDK can assist you in interacting with and configuring your local OpenShift instance, see the OpenShift Client Binary section.

For more information about the OpenShift cluster architecture, see Architecture Overview in the OpenShift documentation.

The following steps describe how to get started with CDK on a Linux operating system with the KVM hypervisor driver.

The minishift setup-cdk command gets and configures the components needed to run CDK on your system. By default, minishift setup-cdk places CDK content in your ~/.minishift directory (%USERPROFILE%/.minishift on Windows).

Run the following command to set up CDK for Red Hat Enterprise Linux:

$ minishift setup-cdk
Setting up CDK 3 on host using '/home/user/.minishift' as Minishift's home directory
Copying minishift-rhel7.iso to '/home/user/.minishift/cache/iso/minishift-rhel7.iso'
Copying oc to '/home/user/.minishift/cache/oc/v3.10.45/linux/oc'
Creating configuration file '/home/user/.minishift/config/config.json'
Creating marker file '/home/user/.minishift/cdk'
Default add-ons anyuid, admin-user, xpaas, registry-route, che, eap-cd installed
Default add-ons anyuid, admin-user, xpaas enabled
CDK 3 setup complete.

For Windows or macOS: Running the minishift setup-cdk command on Windows and macOS results in slightly different output, based on some different components and pathnames.

For more information about interacting with OpenShift with the command line interface and the Web console, see the OpenShift Client Binary section.

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.

This section describes how you can uninstall the minishift binary and delete associated files.

When you use CDK, you interact with the following components:

The CDK architecture diagram outlines these components. The minishift binary, placed on the PATH for easy execution, is used to start, stop, and delete the CDK VM. The VM itself is bootstrapped off of a Red Hat Enterprise Linux Live ISO.

Some CDK commands, for example docker-env, interact with the Docker daemon, whilst others communicate with the OpenShift cluster, for example the openshift command.

Once the OpenShift cluster is up and running, you interact with it using the oc binary. CDK caches this binary under $MINISHIFT_HOME (per default ~/.minishift). minishift oc-env is an easy way to add the oc binary to your PATH.

For more details about using CDK to manage your local OpenShift cluster, see Chapter 3, Interacting with OpenShift using Container Development Kit.

Figure 2.1. : CDK architecture

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

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

$ minishift setup-cdk --minishift-home ~/.mynewdir
$ export MINISHIFT_HOME=~/.mynewdir
$ echo 'export MINISHIFT_HOME=~/.mynewdir' >> ~/.bashrc

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

$ minishift config set --global memory 8192

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

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

$ minishift config view
- memory: 4096

$ minishift config view --global
- memory: 8192

$ minishift config get memory
4096

$ minishift config unset memory

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 CDK VM.

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.

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

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

You can run minishift ssh without a sub-command to open an interactive shell and run commands on the CDK 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 CDK VM and return the result to your local shell. For example:

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

A profile is an instance of the Minishift VM along with all of its configuration and state. The profile feature allows you to create and manage these isolated instances of Minishift.

Each CDK profile is created with its own configuration (memory, CPU, disk size, add-ons, and so on) and is independent of other profiles. Refer to the use of environment variables if you want to make sure that certain configuration settings, for example cpus or memory, get applied to all profiles.

The active profile is the profile against which all commands are executed, unless the global --profile flag is used. You can determine the active profile by using the minishift profile list command. You can execute single commands against a non-active profile by using the --profile flag, for example minishift --profile profile-demo console to open the OpenShift console for the specified profile-demo profile.

On top of the --profile flag, there are commands for listing, deleting and setting the active profile. These commands are described in the following sections.

There are two ways to create a new profile.

$ minishift --profile profile-demo start
-- Checking if requested hypervisor 'xhyve' is supported on this platform ... OK
-- Checking if xhyve driver is installed ...
   Driver is available at /usr/local/bin/docker-machine-driver-xhyve
   Checking for setuid bit ... OK
-- Checking the ISO URL ... OK
-- Starting local OpenShift cluster using 'xhyve' hypervisor ...
-- Minishift VM will be configured with ...
   Memory:    2 GB
   vCPUs :    2
   Disk size: 20 GB
...

$ minishift profile set demo
Profile 'demo' set as active profile

You can list all existing profiles with the minishift profile list command. You can also see the active profile highlighted in the output.

$ minishift profile list
- minishift     Running     	(Active)
- profile-demo  Does Not Exist

To switch between profiles use the minishift profile set command:

$ minishift profile set profile-demo
Profile 'profile-demo' set as active profile

To delete a profile, run:

$ minishift profile delete profile-demo
You are deleting the active profile. It will remove the VM and all related artifacts. Do you want to continue [y/N]?: y
Deleted:  /Users/user/.minishift/profiles/profile-demo
Profile 'profile-demo' deleted successfully
Switching to default profile 'minishift' as the active profile.

You have two options to create a new profile and configure its persistent configuration. The first option is to implicitly create the new profile by making it the active profile using the profile set command. Once the profile is active you can run any minishift config command. Lastly, start the instance:

$ minishift profile set profile-demo
$ minishift config set memory 8GB
$ minishift config set cpus 4
$ minishift addon enable anyuid
$ minishift start

The alternative is to execute a series of commands each specifying the targeted profile explicitly using the --profile flag:

$ minishift --profile profile-demo config set memory 8GB
$ minishift --profile profile-demo config set cpus 4
$ minishift --profile profile-demo addon enable anyuid
$ minishift --profile profile-demo minishift start

To speed up the provisioning of the OpenShift cluster and to minimize network traffic, container images can be cached on the host. These images can then be imported into the running Docker daemon, either explicitly on request or implicitly during minishift start. The following sections describe image caching and its configuration in more detail.

$ minishift delete --clear-cache

CDK provides the image command together with its sub-commands to control the behavior of image caching. To export and import images from the Docker daemon of the CDK VM, use minishift image export and minishift image import.

$ minishift image export <image-name-0> <image-name-1> ...
Pulling image <image-name-0> .. OK
Exporting <image-name-0>. OK
Pulling image <image-name-1> .. OK
Exporting <image-name-2>. OK

$ minishift image import <image-name-0> <image-name-1> ...
Importing <image-name-0> . OK

$ minishift image list
registry.access.redhat.com/openshift3/ose-docker-registry:v3.11.157
registry.access.redhat.com/openshift3/ose-haproxy-router:v3.11.157
registry.access.redhat.com/openshift3/ose:v3.11.157

$ minishift image list --vm
registry.access.redhat.com/openshift3/ose-deployer:v3.11.157
registry.access.redhat.com/openshift3/ose-docker-registry:v3.11.157
registry.access.redhat.com/openshift3/ose-haproxy-router:v3.11.157
registry.access.redhat.com/openshift3/ose-pod:v3.11.157
registry.access.redhat.com/openshift3/ose-web-console:v3.11.157
registry.access.redhat.com/openshift3/ose:v3.11.157

$ minishift image cache-config view
$ minishift image cache-config add alpine:latest busybox:latest
$ minishift image cache-config view
alpine:latest
busybox:latest

$ minishift image cache-config remove alpine:latest
$ minishift image cache-config view
busybox:latest

Image caching is enabled by default for CDK. It occurs in a background process after the minishift start command is completed for the first time. Once the images are cached under $MINISHIFT_HOME/cache/image, successive CDK VM creations will use these cached images.

To disable this feature you need to disable the image-caching property in the persistent configuration using the minishift config set command:

$ minishift config set image-caching false

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

$ minishift config unset image-caching

Images are cached under $MINISHIFT_HOME/cache/images and stored as an SHA256 blob along with an index which contains details about matching the SHA with an image name.

To delete an image from the local cache, use the minishift image delete command:

$ minishift image delete <image-name-0> <image-name-1> ...
Deleting <image-name-0> from the local cache OK
Deleting <image-name-1> from the local cache OK

CDK allows you to extend the vanilla OpenShift setup provided by cluster up with an add-on mechanism.

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

The following example shows the contents of an add-on file, including the name and description of the add-on, additional metadata, and the actual add-on commands to apply.

# Name: anyuid                                                                          1
# Description: Allows authenticated users to run images under a non pre-allocated UID   2
# Required-Vars: ACME_TOKEN                                                             3
# OpenShift-Version: >3.6.0                                                             4
# Minishift-Version: >1.22.0                                                            5

mytoken := oc sa get-token oauth-client                                                 6

oc new-app -p OPENSHIFT_OAUTH_CLIENT_SECRET=#{mytoken}                                  7
oc adm policy add-scc-to-group anyuid system:authenticated                              8

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

As part of the add-on metadata you can specify the OpenShift version which needs to be running in order to apply the add-on. To do so, you can specify the optional OpenShift-Version metadata field. The semantics are as follows:

As part of the add-on metadata you can specify the Minishift version which needs to be running in order to apply the add-on. To do so, you can specify the optional Minishift-Version metadata field. The semantics are as follows:

Add-on dependencies can be defined using the Depends-On metadata field. Multiple dependencies may be defined using a comma-separated list of add-on names.

# Name: example
# Description: Shows the use of the Depends-On metadata field
# Depends-On: anyuid, admin-user

echo Depends on the anyuid and admin-user add-ons, requiring them to be installed.

This section describes the commands that an add-on file can contain. They form a small domain-specific language for CDK add-ons:

CDK allows the use of variables within the add-on commands. Variables have the format #{<variable-name>}. The following example shows how the OpenShift routing suffix can be interpolated into an openshift command to create a new certificate as part of securing the OpenShift registry. The used variable #{routing-suffix} is part of the built-in add-on variables.

$ 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 apply --addon-env PROJECT_USER=user acme

$ minishift config set addon-env PROJECT_USER=user
$ minishift addons apply acme

$ minishift config set addon-env PROJECT_USER=env.USER        1
$ minishift addons apply acme                                 2

# Name: acme
# Description: ACME add-on
# Required-Vars: PROJECT_USER

# Name: acme
# Description: ACME add-on
# Required-Vars: PROJECT_USER
# Var-Defaults: PROJECT_USER=user

mytoken := oc sa get-token oauth-client
oc new-app -p OPENSHIFT_OAUTH_CLIENT_SECRET=#{mytoken}

CDK provides a set of built-in add-ons that offer some common OpenShift customization to assist with development. During minishift setup-cdk, Minishift automatically installs and enables the xpaas, anyuid, and admin-user add-ons. To install the default add-ons, run:

$ minishift addons install --defaults

This command extracts the default add-ons to the add-on installation directory $MINISHIFT_HOME/addons. To view the list of installed add-ons, you can then run:

$ minishift addons list --verbose=true

This command prints a list of installed add-ons. You should at least see the anyuid add-on listed. This is an important add-on that allows you to run images that do not use a pre-allocated UID. By default, this is not allowed in OpenShift.

Add-ons are installed with the minishift addons install command.

The following example shows how to install an add-on.

$ minishift addons install <path_to_addon_directory>

Add-ons are enabled with the minishift addons enable command and disabled with the minishift addons disable command. Enabled add-ons automatically get executed during minishift start.

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)

Add-ons can be explicitly executed with the minishift addons apply command. You can use the apply command for both enabled and disabled add-ons. To apply multiple add-ons with a single command, specify add-on names separated by space.

The following example shows how to explicitly apply the anyuid and the admin-user add-ons.

$ minishift addons apply anyuid admin-user

Add-ons can be removed with the minishift addons remove command. It is the mirror command to minishift addons apply and similarly can be used regardless of whether the add-on is enabled or not. Provided the specified add-on is installed and has a <addon_name>.addon.remove file, minishift addons remove will execute the commands specified in this file.

To remove multiple add-ons with a single command, specify the add-on names separated by a space. The following example shows how to explicitly remove the admin-user add-on.

$ minishift addons remove admin-user
-- Removing addon 'admin-user':.
admin user deleted

Add-ons can be uninstalled with the minishift addons uninstall command. It is the mirror command to minishift addons install and can be used regardless of whether the add-on is enabled or not. Provided the specified add-on is installed, minishift addons uninstall will delete the corresponding add-on directory from $MINISHIFT_HOME/addons.

The following example shows how to explicitly uninstall the admin-user add-on:

$ minishift addons uninstall admin-user
Add-on 'admin-user' uninstalled

To write a custom add-on, you should create a directory and in it create at least one text file with the extension .addon, for example admin-role.addon.

This file needs to contain the Name and Description metadata fields, as well as the commands that you want to execute as a part of the add-on.

The following example shows the definition of an add-on that gives the developer user cluster-admin privileges.

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

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

After you define the add-on, you can install it by running:

$ minishift addons install <ADDON_DIR_PATH>

# Name: prometheus
# Description: This template creates a Prometheus instance preconfigured to gather OpenShift and
# Kubernetes platform and node metrics and report them to admins. It is protected by an
# OAuth proxy that only allows access for users who have view access to the prometheus
# namespace. You may customize where the images (built from openshift/prometheus
# and openshift/oauth-proxy) are pulled from via template parameters.
# Url: https://prometheus.io/

You can also edit your add-on directly in the CDK add-on install directory $MINISHIFT_HOME/addons. Be aware that if there is an error in the add-on, it will not show when you run any addons commands, and it will not be applied during the minishift start process.

To provide add-on removal instructions, you can create text file with the extension .addon.remove, for example admin-user.addon.remove. Similar to the .addon file, it needs the Name and Description metadata fields. If a .addon.remove file exists, it can be applied via the remove command.

Host folders are directories on the host which are shared between the host and the CDK VM. This allows for two way file synchronization between the host and the VM. The following sections discuss usage of the minishift hostfolder command.

CDK provides the minishift hostfolder command to list, add, mount, unmount and remove host folders. You can use the hostfolder command to mount multiple shared folders onto custom specified mount points.

$ minishift hostfolder list
Name    Type    Source               Mountpoint       Mounted
test    sshfs   /Users/user/test     /mnt/sda1/test   N

$ minishift hostfolder add -t cifs --source //192.168.99.1/MYSHARE --target /mnt/sda1/myshare --options username=user,password=mysecret,domain=MYDOMAIN myshare

$ minishift hostfolder add -t sshfs --source /Users/user/myshare --target /mnt/sda1/myshare myshare

$ minishift hostfolder add -t sshfs --source ~/myshare/ --target /mnt/sda1/myshare --options "-o compression=no" myshare

$ minishift hostfolder mount myshare

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

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

$ minishift config set hostfolders-sftp-port 2222

$ minishift config set hostfolders-automount true

$ minishift hostfolder umount myshare

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

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

$ minishift hostfolder remove myshare

$ minishift hostfolder list
No host folders defined

Most hypervisors do not support extending the lease time when the IP is assigned using DHCP. This might lead to a new IP being assigned to the VM after a restart as it will conflict with the security certificates generated for the old IP. This will make CDK completely unusable until a new instance is set up by running minishift delete followed by minishift start.

To prevent this, CDK includes the functionality to set a static IP address to the VM. This will prevent the IP address from changing between restarts. However, it will not work on all of the driver plug-ins at the moment due to the way the IP address is resolved.

Since the Internal Virtual Switch for Hyper-V does not provide a DHCP offer option, an IP address needs to be provided in a different way. Functionality is provided to assign an IP address on startup using the Data Exchange Service for Hyper-V.

To make this work, you need to create a Virtual Switch using NAT.

The following command will attempt to assign an IP address for use on the Internal Virtual Switch 'MyInternal':

PS> minishift.exe config set hyperv-virtual-switch "MyInternal"
PS> minishift.exe start `
  --network-ipaddress 192.168.1.10 `
  --network-gateway 192.168.1.1 `
  --network-nameserver 8.8.8.8

If you want to use the 'DockerNAT' network, the following commands are needed to setup the correct NAT networking and assign an IP in the range expected:

PS> New-NetNat -Name SharedNAT -InternalIPInterfaceAddressPrefix 10.0.75.1/24
PS> minishift.exe config set hyperv-virtual-switch "DockerNAT"
PS> minishift.exe start `
  --network-ipaddress 10.0.75.128 `
  --network-gateway 10.0.75.1 `
  --network-nameserver 8.8.8.8

The following command will set the IP address that was assigned as fixed:

$ minishift ip --set-static

If you prefer to use dynamic assignment, you can use:

$ minishift ip --set-dhcp

When running OpenShift in a single VM, you can reuse the Docker daemon managed by CDK for other Docker use-cases as well. By using the same Docker daemon as CDK, you can speed up your local development.

In order to configure your console to reuse the CDK Docker daemon, follow these steps:

If you want to get early access to some upcoming features and experiment, you can set the environment variable MINISHIFT_ENABLE_EXPERIMENTAL, which makes additional feature flags available:

$ export MINISHIFT_ENABLE_EXPERIMENTAL=y

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

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

For example, the following command will provision the OpenShift service catalog:

$ MINISHIFT_ENABLE_EXPERIMENTAL=y minishift start --extra-clusterup-flags "--enable='*,service-catalog'"

To help in the situation when security certificates are used in an organization, but cannot be easily shared with the instance, CDK can run a local proxy server on the host, which the CDK instance can use to access external resources.

Enabling the proxy server is done using the following command:

$ minishift config set local-proxy true

This will start a proxy server on the host which will be automatically assigned to the CDK instance.

When the corporate or upstream proxy is known, you can specify this with the following configuration option:

$ minishift config set local-proxy-upstream http(s)://[username:password@]host:port

When this option is used, all traffic will be re-encrypted with a CDK-specific certificate. For this reason, this proxy should only be used for development and use with CDK.

CDK provides a DNS server for offline usage or the possibility of overriding DNS records while testing. This will allow you to access the OpenShift routes without Internet.

Starting the DNS server can be done as follows:

$ minishift dns start

After starting the DNS server you need to configure your device settings to use this nameserver. The start command will show you a temporary option that can be used when you entered offline usage.

Stopping the DNS server can be done as follows:

$ minishift dns stop

To get the status of the DNS server:

$ minishift dns status

$ ls /dev | grep tap

$ brew install tuntap

<key>D16F22CE-6DDE-4E63-837C-E16538EA5CCB</key>	1
<dict>
    <key>DNS</key>
    <dict />
    <key>IPv4</key>
    <dict>
        <key>Addresses</key>
        <array>
            <string>10.10.90.1</string>		2
        </array>
        <key>ConfigMethod</key>
        <string>Manual</string>
        <key>SubnetMasks</key>
        <array>
            <string>255.255.0.0</string>
        </array>
    </dict>
    <key>IPv6</key>
    <dict>
        <key>ConfigMethod</key>
        <string>Automatic</string>
    </dict>
    <key>Interface</key>
    <dict>
        <key>DeviceName</key>
        <string>tap0</string>			3
        <key>Hardware</key>
        <string>Ethernet</string>
        <key>Type</key>
        <string>Ethernet</string>
        <key>UserDefinedName</key>
        <string>MiniTap</string>		4
    </dict>
    <key>Proxies</key>
    <dict>
        <key>ExceptionsList</key>
        <array>
            <string>*.local</string>
            <string>169.254/16</string>
        </array>
        <key>FTPPassive</key>
        <integer>1</integer>
    </dict>
    <key>SMB</key>
    <dict />
    <key>UserDefinedName</key>
    <string>MiniTap</string>			5
</dict>

<key>ServiceOrder</key>
    <array>
        <string>06BFF3C7-13DA-420F-AE9C-B036401184D7</string>
	<string>58231F56-CA25-4D41-930F-46D83CA07BFE</string>
	<string>304203B0-AC87-459F-9761-C2799EEBB2E3</string>
	<string>8655D244-C6E7-4CC0-BF06-BB18F9C3BB85</string>
	<string>3C26FB9D-D918-4B79-9C7B-ADECD8EFE00F</string>
	<string>D16F22CE-6DDE-4E63-837C-E16538EA5CCB</string>	1
    </array>

<key>Service</key>
    <dict>
        <key>06BFF3C7-13DA-420F-AE9C-B036401184D7</key>
        <dict>
            <key>__LINK__</key>
            <string>/NetworkServices/06BFF3C7-13DA-420F-AE9C-B036401184D7</string>
        </dict>
        <key>304203B0-AC87-459F-9761-C2799EEBB2E3</key>
        <dict>
            <key>__LINK__</key>
            <string>/NetworkServices/304203B0-AC87-459F-9761-C2799EEBB2E3</string>
        </dict>
        <key>3C26FB9D-D918-4B79-9C7B-ADECD8EFE00F</key>
        <dict>
            <key>__LINK__</key>
            <string>/NetworkServices/3C26FB9D-D918-4B79-9C7B-ADECD8EFE00F</string>
        </dict>
        <key>58231F56-CA25-4D41-930F-46D83CA07BFE</key>
        <dict>
            <key>__LINK__</key>
            <string>/NetworkServices/58231F56-CA25-4D41-930F-46D83CA07BFE</string>
        </dict>
        <key>8655D244-C6E7-4CC0-BF06-BB18F9C3BB85</key>
        <dict>
            <key>__LINK__</key>
            <string>/NetworkServices/8655D244-C6E7-4CC0-BF06-BB18F9C3BB85</string>
        </dict>
        <key>D16F22CE-6DDE-4E63-837C-E16538EA5CCB</key>				  1
        <dict>
            <key>__LINK__</key>
            <string>/NetworkServices/D16F22CE-6DDE-4E63-837C-E16538EA5CCB</string>2
        </dict>
    </dict>

$ exec 4<>/dev/tap0			1
$ ifconfig tap0 10.10.90.1 255.255.0.0  2 3
$ ifconfig tap0 up			4

nameserver <ip_address_of_the_minishfit_vm>
search_order 1

To help the users of CDK on macOS and Windows perform simple tasks like starting and stopping a profile from the GUI, the binaries for these platforms have been compiled to include an experimental system tray.

By default, the system tray is automatically started on running minishift start. To disable this behavior, use the following command:

$ minishift config set auto-start-tray false

To start the system tray:

$ minishift service start systemtray

If you want to set a different timezone from the default, use the following command:

$ minishift timezone --set <Valid_Timezone>

To see the available timezones, use the following command:

$ minishift timezone --list

To check the current timezone of the CDK instance, use the following command:

$ minishift timezone

CDK can be run against an existing remote machine using vm-driver as generic.

To use an existing machine with CDK, it needs to be configured as follows:

Use the following command on the host to run CDK against a remote machine:

$ minishift start --vm-driver generic --remote-ipaddress <remote_IP_address> --remote-ssh-user <username> --remote-ssh-key <private_ssh_key>
$ minishift addon apply htpasswd-identity-provider --addon-env USER_PASSWORD=<NEW_PASSWORD>

Kompose is a tool for converting Docker Compose to container orchestrators such as OpenShift and Kubernetes. Kompose may be installed manually or via a package manager (Chocolatey on Microsoft Windows, Homebrew on macOS, or Yum on Red Hat Enterprise Linux).

PS> choco.exe install kubernetes-kompose

$ brew install kompose

$ subscription-manager repos --enable rhel-7-server-devtools-rpms
$ subscription-manager repos --enable rhel-server-rhscl-7-rpms
$ yum install kompose -y

To convert your Docker Compose project using Kompose, follow these steps:

The minishift start command creates an OpenShift cluster using the cluster up approach. For this purpose it copies the oc binary onto your host.

The oc binary is located in the $MINISHIFT_HOME/cache/oc/v3.11.157 directory, assuming that you use the default OpenShift version for CDK. 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 minishift oc-env differs depending on the operating system and the shell type.

$ minishift oc-env
export PATH="/home/user/.minishift/cache/oc/v3.11.157:$PATH"
# Run this command to configure your shell:
# eval $(minishift oc-env)

As part of the minishift start command, a CLI profile named minishift is also created. This profile, also known as a context, contains the configuration to communicate with your OpenShift cluster.

CDK 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, see 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 is developer and developer, respectively. This is because they are already assigned to the default project myproject and also can impersonate the administrator. This allows you 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 available login contexts, run:

$ oc config view

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

$ minishift console --url

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

$ minishift console

To access a service that is exposed with a route, run this command in a shell:

$ minishift openshift service [-n NAMESPACE] [--url] NAME

For more information refer also to Exposing Services.

To access OpenShift logs, run the following command after starting CDK:

$ minishift logs

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

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

$ minishift openshift config view

To show the node or kubeapi-server configuration instead of the master configuration, specify the target flag.

For details about the view sub-command, see the minishift openshift config view synopsis.

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

PS> minishift.exe openshift config set --patch '{\"corsAllowedOrigins\": [\".*\"]}'

C:\> minishift.exe openshift config set --patch "{\"corsAllowedOrigins\": [\".*\"]}"

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

To add a component to a running OpenShift cluster, use the following:

$ minishift openshift component add <component-name>

$ minishift openshift component add service-catalog

To list valid components which can be added to the running OpenShift cluster, use the following:

$ minishift openshift component list

There are several ways you can expose your service after you deploy it on OpenShift. The following sections describe the various methods and when to use them.

If you are deploying a Web application, the most common way to expose it is by a route. A route exposes the service as a host name. You can create a route using the Web console or the CLI:

$ oc expose svc/frontend --hostname=www.example.com

To see a full example of creating an application and exposing it with a route, see the Deploying a Sample Application section.

In case the service you want to expose is not HTTP based, you can create a NodePort service. In this case, each OpenShift node will proxy that port into your service. To access this port on your CDK VM, you need to configure an Ingress IP using oc expose with the parameter type=LoadBalancer.

A common use-case for Ingress IP Self-Service is the ability to expose a database service. The following example shows the complete workflow to create and expose a MariaDB instance using CDK:

$ minishift start
$ eval $(minishift oc-env)
$ oc new-app -e MYSQL_ROOT_PASSWORD=admin https://raw.githubusercontent.com/openshift/origin/master/examples/db-templates/mariadb-persistent-template.json
$ oc rollout status -w dc/mariadb
$ oc expose dc mariadb --type=LoadBalancer --name=mariadb-ingress
$ oc export svc mariadb-ingress
 ....
ports:
    - nodePort: 30907
 ....

After the service is exposed, you can access MariaDB with the mysql CLI using the CDK VM IP and the exposed NodePort service.

$ mysql --user=root --password=admin --host=$(minishift ip) --port=30907

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

The following example shows how to deploy an OpenShift application directly from a locally-built Docker image. This example uses the OpenShift project myproject. This project is automatically created by minishift start.

$ oc run myapp --image 172.30.1.1:5000/myproject/myapp

This section contains solutions to common problems that you might encounter while installing and configuring CDK.

While CDK starts, it runs several startup checks to make sure that the CDK VM and the OpenShift Cluster are able to start without any issues. If any configuration is incorrect or missing, the startup checks fail and CDK does not start.

The following sections describe the different startup checks.

$ minishift config set skip-check-storage-usage true

$ minishift config set check-network-ping-host <host-IP-address>

$ minishift config set check-network-http-host <URL>

minishift console does not work on older versions of Safari web browser such as version 10.1.2 (12603.3.8). Attempting to access the web console results in the following error:

Error unable to load details about the server

Retry after updating it to the latest version or use Firefox or Chrome browser for this. Version 11.0.3 (13604.5.6) has been tested and works with OpenShift web console. You can use minishift console --url to get the web console URL.

This section contains solutions to common problems that you might encounter while configuring the driver plug-ins for CDK.

This section contains solutions to common problems that you might encounter while using various components of CDK.

Installing additional packages or copying large files to the root filesystem of the CDK VM might exceed the allocated overlay size and lock the CDK VM.

Cause: The CDK VM root filesystem contains core packages that are configured to optimize running the CDK VM and containers. The available storage on the root filesystem is determined by the overlay size, which is smaller than the total available storage.

Workaround: Avoid installing packages or storing large files in the root filesystem of the CDK VM. Instead, you can create a sub-directory in the /mnt/sda1/ persistent storage volume or define and mount host folders that can share storage space between the host and the CDK VM.

If you want to perform development tasks inside the CDK VM, it is recommended that you use containers, which are stored in persistent storage volumes, and reuse the CDK Docker daemon.

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>'

Attempting to access the OpenShift web console using Microsoft Edge can result in the following error:

Site not reachable.

Alternatively, the OpenShift web console may be rendered as a blank page.

Cause: This is an inconsistent error caused by Microsoft Edge.

Workaround: Use an alternative web browser to access the OpenShift web console. Mozilla Firefox and Google Chrome both work as expected.

Starting a stopped CDK VM can produce the following X.509 certificate error:

$ minishift start
-- Checking if requested hypervisor 'kvm' is supported on this platform ... OK
-- Checking the ISO URL ... OK
-- Starting local OpenShift cluster using 'kvm' hypervisor ...
-- Starting Minishift VM ......................... OK
[...]
FAIL
   Error: cannot access master readiness URL https://192.168.99.101:8443/healthz/ready
   Details:
     No log available from "origin" container

   Caused By:
     Error: Get https://192.168.99.101:8443/healthz/ready: x509: certificate is valid for 10.0.2.15, 127.0.0.1, 172.17.0.1, 172.30.0.1, 192.168.99.100, not 192.168.99.101
Error during 'cluster up' execution: Error starting the cluster.

The reason for the above error is that OpenShift cluster certificates contain the IP of the CDK VM. The certificates are generated only when the CDK VM is freshly started. After restart, the CDK VM might be assigned a new IP address. If this happens, the certificate becomes invalid.

Workaround: Delete the existing CDK VM and start again.

$ minishift delete --force
$ minishift start