Chapter 1. Getting Started with Container Development Kit

Refer to the following documents for further information:

To report issues, refer to the following:

Container Development Kit 3.2 is based on Minishift 1.7.0. Using a single executable file, the minishift command deploys CDK as a Red Hat Enterprise Linux virtual machine, running OpenShift (which includes Kubernetes, the Docker service, and other container development and deployment software).

The CDK setup procedure can, and should, be run as a regular user that has special 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.

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

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 (as described in the coming setup procedure).

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

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

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

The following steps describe how to prepare your virtualization environment (hypervisor) for CDK, download CDK software, set up CDK, and start using it.

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

Some hypervisors require manual installation of the driver plug-in. CDK embeds VirtualBox drivers so no additional steps are required to configure the driver. However, a minishift command option (--vm-driver virtualbox) will be required later to identify VirtualBox to CDK.

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

$ 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 needs 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

Before you can download CDK software, you need to either register with the Red Hat Developer Program site or login to the Red Hat customer portal with Red Hat subscription credentials. Then go to one of the following two sites and download the software associated with your operating system:

Copy the downloaded minishift file to a directory in your PATH and make it executable. The downloaded executable is named cdk-3.2.0-1-minishift-darwin-amd64 (for macOS), cdk-3.2.0-1-minishift-linux-amd64 (for Linux) or cdk-3.2.0-1-minishift-windows-amd64.exe (for Windows). Assuming the executable is in the ~/Downloads directory, follow the procedure for your operating system:

For Red Hat Enterprise Linux:

mkdir -p ~/bin
cp ~/Downloads/cdk-3.2.0-1-minishift* ~/bin/minishift
chmod +x ~/bin/minishift
export PATH=$PATH:$HOME/bin
echo ‘export PATH=$PATH:$HOME/bin’ >> ~/.bashrc

$ mkdir -p ~/bin
$ cp ~/Downloads/cdk-3.2.0-1-minishift* ~/bin/minishift
$ chmod +x ~/bin/minishift
$ export PATH=$PATH:$HOME/bin
$ echo ‘export PATH=$PATH:$HOME/bin’ >> ~/.bashrc

For macOS:

mkdir -p ~/bin
cp ~/Downloads/cdk-3.2.0-1-minishift* ~/bin/minishift
chmod +x ~/bin/minishift
export PATH=$PATH:$HOME/bin
echo export PATH=$PATH:$HOME/bin >> ~/.bash_profile

$ mkdir -p ~/bin
$ cp ~/Downloads/cdk-3.2.0-1-minishift* ~/bin/minishift
$ chmod +x ~/bin/minishift
$ export PATH=$PATH:$HOME/bin
$ echo export PATH=$PATH:$HOME/bin >> ~/.bash_profile

For Windows:

Create the desired directory and copy the downloaded CDK binary to the directory, renaming the binary to minishift.exe. Add the directory path to the Windows PATH variable.

If it’s difficult to get minishift.exe in your PATH, you can simply run it from the current directory as ./minishift.exe (or .\minishift.exe in some Windows shells).

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

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

As you can see from the output, a .minishift directory is created in the user’s home directory to hold various CDK components, and appropriate files and settings are stored there.

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

Currently, CDK cannot automatically download the oc binary for OpenShift Container Platform 3.7. However, you may manually download the oc 3.7 binary to use it. To do so, follow these steps:

minishift start --ocp-tag v3.7.0.0.198.0

$ minishift start --ocp-tag v3.7.0.0.198.0

The minishift start command launches CDK, which consists of a Red Hat Enterprise Linux virtual machine running OpenShift Container Platform. Follow these steps to launch CDK.

You will see similar output from minishift start when run in a macOS terminal or Windows command prompt or PowerShell.

With the CDK virtual machine running, you can configure and start using CDK through two primary interfaces: oc (OpenShift client binary command) or the OpenShift web console.

For more information about interacting with OpenShift from the command-line interface, see the OpenShift Client Binary section.

You are now ready to start using OpenShift using either of those two interfaces.

OpenShift provides various sample applications, such as templates, builder applications, and quickstarts. To begin creating an application, see:

The following steps describe how to deploy a sample Node.js application from the command-line.

See minishift stop for details on managing subscriptions as you stop and start the VM.

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.