Chapter 1. Getting started with Container Development Kit

This section contains information about setting up, installing, and uninstalling Container Development Kit.

1.1. Introducing Red Hat Container Development Kit

Red Hat Container Development Kit provides a platform for developing containerized applications. It is a set of tools that enables developers to quickly and easily set up an environment for developing and testing containerized applications on the Red Hat Enterprise Linux platform.

  • Container Development Kit provides a personal Container Development Environment you can install on your own laptop, desktop, or server system. The Container Development Environment is provided in the form of a Red Hat Enterprise Linux virtual machine.
  • Container Development Kit is available for the Microsoft Windows, macOS, and Linux operating systems, thus allowing developers to use their preferred platform while producing applications ready to be deployed in the Red Hat Enterprise Linux ecosystem.

Container Development Kit is a part of the Red Hat Developers program, which provides tools, resources, and support for developers who wish to utilize Red Hat solutions and products to create applications, both locally and in the cloud. For additional information and to register to become a part of the program, visit developers.redhat.com.

1.1.1. Understanding Container Development Kit documentation

1.2. Preparing to Install CDK

1.2.1. Overview

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:

  1. Set up your virtualization environment
  2. Download CDK software for your operating system from the Red Hat Container Development Kit Download page
  3. Install CDK
  4. Set up and start CDK
  5. Configure CDK so you can use it efficiently

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.

1.2.2. Prerequisites

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:

macOS
Linux
Windows
All Platforms

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

1.3. Setting Up the Virtualization Environment

1.3.1. Overview

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:

1.3.2. Red Hat Enterprise Linux

1.3.2.1. Setting Up the KVM Driver

CDK is currently tested against docker-machine-driver-kvm version 0.10.0.

  1. As root, install the KVM binary and make it executable as follows: 

    # curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.10.0/docker-machine-driver-kvm-centos7 -o /usr/local/bin/docker-machine-driver-kvm
# chmod +x /usr/local/bin/docker-machine-driver-kvm

    For more information, see the GitHub documentation of the Docker Machine KVM driver.

  2. As root, install libvirt and qemu-kvm on your system: 

    # yum install libvirt qemu-kvm

  3. As root, add yourself to the libvirt group: 

    # usermod -a -G libvirt username

  4. Update your current session to apply the group change: 

    $ newgrp libvirt

  5. Start the libvirtd service as root: 

    # systemctl start libvirtd
# systemctl enable libvirtd

1.3.2.2. Start libvirtd service

  1. Check the status of libvirtd: 
$ systemctl is-active libvirtd
  1. If libvirtd is not active, start the libvirtd service as root: 
# systemctl start libvirtd
1.3.2.2.1. Next Steps

Proceed to Installing CDK once your hypervisor has been installed and configured.

1.3.3. macOS

1.3.3.1. Setting Up the hyperkit Driver

CDK is currently tested against docker-machine-driver-hyperkit version 1.0.0.

Using hyperkit requires having both hyperkit and docker-machine-driver-hyperkit installed.

1.3.3.1.1. Installing hyperkit
$ brew install hyperkit
1.3.3.1.2. Installing docker-machine-driver-hyperkit
  • If you use Homebrew you can install the latest version of docker-machine-driver-hyperkit: 
$ brew install docker-machine-driver-hyperkit
  • Alternatively, you can download and install the docker-machine-driver-hyperkit binary and place it in a directory which is on your PATH environment variable. The directory /usr/local/bin is a good choice, since it is the default installation directory for Docker Machine binaries.

The following steps explain the installation of the docker-machine-driver-hyperkit binary to the /usr/local/bin/ directory:

  1. Download the docker-machine-driver-hyperkit binary using: 

    $ sudo curl -L  https://github.com/machine-drivers/docker-machine-driver-hyperkit/releases/download/v1.0.0/docker-machine-driver-hyperkit -o /usr/local/bin/docker-machine-driver-hyperkit

  2. Enable root access for the docker-machine-driver-hyperkit binary and add it to the default wheel group: 

    $ sudo chown root:wheel /usr/local/bin/docker-machine-driver-hyperkit

  3. Set owner User ID (SUID) for the binary as follows: 

    $ sudo chmod u+s,+x /usr/local/bin/docker-machine-driver-hyperkit
Note

The downloaded docker-machine-driver-hyperkit binary is compiled against a specific version of macOS. It is possible that the driver will fail to work after a macOS version upgrade. In this case you can try to compile the driver from source: 

$ go get -u -d github.com/machine-drivers/docker-machine-driver-hyperkit
$ cd $GOPATH/src/github.com/machine-drivers/docker-machine-driver-hyperkit

# Install docker-machine-driver-hyperkit binary into /usr/local/bin
$ make build

For more information, see the hyperkit driver documentation on GitHub.

1.3.3.1.3. Next Steps

Proceed to Installing CDK once your hypervisor has been installed and configured.

1.3.4. Windows

1.3.4.1. Setting Up the Hyper-V Hypervisor

To use CDK with Hyper-V:

  1. Install Hyper-V.

  2. Add the user to the local Hyper-V Administrators group.

    Note

    This is required to allow the user to create and delete virtual machines with the Hyper-V Management API. For more information, see Hyper-V commands must be run as an Administrator.

  3. Add an External Virtual Switch.
  4. Verify that you pair the virtual switch with a network card (wired or wireless) that is connected to the network.

  5. Use the configuration option hyperv-virtual-switch or startup flag --hyperv-virtual-switch to set the name of the external virtual switch you want to use for CDK.

    For example, on PowerShell use 

    PS> minishift config set hyperv-virtual-switch "External (Wireless)"

    or 

    PS> minishift start --hyperv-virtual-switch "External (Wireless)"
    Note
    • The name of the virtual switch is case sensitive.
    • The use of the environment variable HYPERV_VIRTUAL_SWITCH has been deprecated. Instead MINISHIFT_HYPERV_VIRTUAL_SWITCH can be used as a configuration option, although this is not recommended as environment variables on Windows do not support non-ASCII characters.
1.3.4.1.1. Next Steps

Proceed to Installing CDK once your hypervisor has been installed and configured.

1.3.5. Setting Up CDK to Use VirtualBox

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.

1.3.5.1. Use VirtualBox Temporarily

The --vm-driver virtualbox flag will need to be given on the command line each time the minishift start command is run. For example: 

$ minishift start --vm-driver virtualbox

1.3.5.2. Use VirtualBox Permanently

Setting the vm-driver option as a persistent configuration option allows you to run minishift start without explicitly passing the --vm-driver virtualbox flag each time. You may set the vm-driver persistent configuration option as follows: 

$ minishift config set vm-driver virtualbox
Note

The vm-driver persistent configuration option must be supplied before minishift start has been run. If you have already run minishift start, ensure that you run minishift delete, set the configuration with minishift config set vm-driver virtualbox, then run minishift start in order to make use of the VirtualBox driver.

1.3.5.3. Next Steps

Proceed to Installing CDK once your hypervisor has been installed and configured.

1.4. Installing CDK

Note

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.

  1. Download CDK for your operating system from the Red Hat Container Development Kit Download page.

  2. Copy the downloaded minishift file to a directory in your PATH and make it executable. The downloaded executable is named cdk-3.16.0-1-minishift-darwin-amd64 (for macOS), cdk-3.16.0-1-minishift-linux-amd64 (for Red Hat Enterprise Linux) or cdk-3.16.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.16.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.16.0-2-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 Command Prompt).

Note
  • On the Windows operating system, due to issue #236, you need to execute the CDK binary from your local C:\ drive. You cannot run CDK from a network drive.

1.5. CDK Quickstart

1.5.1. Overview

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.

1.5.2. Setting up CDK

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

Important

To use a directory other than ~/.minishift, you must set the --minishift-home flag or MINISHIFT_HOME environment variable, as described in Environment Variables.

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.

1.5.3. Starting CDK

  1. By default, minishift start prompts you for your Red Hat Subscription Manager account username and password. You can enter that information or choose instead to:

    • Skip registration: Add the --skip-registration option to minishift start to not register the CDK VM.

    • Register permanently: You can export registration information to environment variables so that minishift picks it up automatically each time it starts.

      Important

      Storing unencrypted registration information in environment variables is not secure. Entering your credentials through the minishift start prompt is recommended for security.

      Export your registration information as follows:

      For Red Hat Enterprise Linux: 

      $ export MINISHIFT_USERNAME='<RED_HAT_USERNAME>'
$ export MINISHIFT_PASSWORD='<RED_HAT_PASSWORD>'
$ echo export MINISHIFT_USERNAME=$MINISHIFT_USERNAME >> ~/.bashrc
$ echo export MINISHIFT_PASSWORD=$MINISHIFT_PASSWORD >> ~/.bashrc

      For macOS: 

      $ export MINISHIFT_USERNAME='<RED_HAT_USERNAME>'
$ export MINISHIFT_PASSWORD='<RED_HAT_PASSWORD>'
$ echo export MINISHIFT_USERNAME=$MINISHIFT_USERNAME >> ~/.bash_profile
$ echo export MINISHIFT_PASSWORD=$MINISHIFT_PASSWORD >> ~/.bash_profile

      For Windows:

      Using Command Prompt: 

      C:\> set MINISHIFT_USERNAME='<RED_HAT_USERNAME>'
C:\> set MINISHIFT_PASSWORD='<RED_HAT_PASSWORD>'
C:\> setx MINISHIFT_USERNAME %MINISHIFT_USERNAME%
C:\> setx MINISHIFT_PASSWORD %MINISHIFT_PASSWORD%

      Using PowerShell: 

      PS> $env:MINISHIFT_USERNAME = '<RED_HAT_USERNAME>'
PS> $env:MINISHIFT_PASSWORD = '<RED_HAT_PASSWORD>'
PS> setx MINISHIFT_USERNAME $env:MINISHIFT_USERNAME
PS> setx MINISHIFT_PASSWORD $env:MINISHIFT_PASSWORD

  2. Run the minishift start command: 

    $ minishift start
-- Starting profile 'minishift'
...
-- Minishift VM will be configured with ...
   Memory:    4 GB
   vCPUs :    2
   Disk size: 20 GB
-- Starting Minishift VM .......................... OK
-- Registering machine using subscription-manager
   Registration in progress ..................... OK [42s]
...
   OpenShift server started.

   The server is accessible via web console at:
       https://192.168.42.60:8443/console

   You are logged in as:
       User:     developer
       Password: <any value>

   To login as administrator:
       oc login -u system:admin
...
    Note
    • The IP is dynamically generated for each OpenShift cluster. To check the IP, run the minishift ip command.
    • By default, CDK uses the driver most relevant to the host OS. To use a different driver, set the --vm-driver flag in minishift start. For example, to use VirtualBox instead of KVM on Linux operating systems, run minishift start --vm-driver=virtualbox.
    • While CDK starts it runs several checks to make sure that the CDK VM and the OpenShift cluster are able to start correctly. If any startup checks fail, see the Troubleshooting Getting Started topic for information about possible causes and solutions.

    For more information about minishift start options, see the minishift start command reference.

  3. 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 environment variable. The output of oc-env will differ depending on OS and shell type. 

    $ minishift oc-env
export PATH="/home/user/.minishift/cache/oc/v3.11.374/linux:$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 OpenShift Client Binary section.

1.5.4. Deploying a Sample Application

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.

  1. Create a Node.js example application: 

    $ oc new-app https://github.com/openshift/nodejs-ex -l name=myapp

  2. Track the build log until the application is built and deployed: 

    $ oc logs -f bc/nodejs-ex

  3. Expose a route to the service: 

    $ oc expose svc/nodejs-ex

  4. Access the application: 

    $ minishift openshift service nodejs-ex --in-browser

  5. To stop CDK, use the following command: 

    $ minishift stop
Stopping local OpenShift cluster...
Unregistering machine
Cluster stopped.

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

1.6. Uninstalling CDK

1.6.1. Overview

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

1.6.2. Uninstalling CDK

  1. Delete the CDK VM and any VM-specific files: 

    $ minishift delete

    This command deletes everything in the MINISHIFT_HOME/.minishift/machines/minishift directory. Other cached data and the persistent configuration are not removed.

  2. To completely uninstall CDK, delete everything in the MINISHIFT_HOME directory (default ~/.minishift):

    For Red Hat Enterprise Linux and macOS: 

    $ rm -rf ~/.minishift

    For Windows PowerShell:

    Replace <MINISHIFT_HOME> with the location of your home directory. 

    PS C:\> Remove-Item -Recurse -Force C:\<MINISHIFT_HOME>\.minishift\

    For Windows command prompt:

    Replace <MINISHIFT_HOME> with the location of your home directory. (You may need to use the del /s command instead.) 

    c:\> rm -r c:\<MINISHIFT_HOME>\.minishift
  3. With your hypervisor management tool, confirm that there are no remaining artifacts related to the CDK VM. For example, if you use KVM, you need to run the virsh command.