Container Development Kit

The prerequisites for running CDK on Red Hat Enterprise Linux are:

• A Red Hat Developer Program username and password are required to enable the Red Hat Enterprise Linux VM included with the CDK to download and build container images from Red Hat.  Please make sure to accept the terms and conditions.
• A virtualization platform, either Linux KVM or VirtualBox.  For KVM you should have libvirt permissions to allow you to start and stop a VM using your normal, non-root user ID.
• 25 GB of free disk space.

All of the commands in this section should be run as the root user.

For more information, see the CDK Getting Started Guide.

1. Enable the Red Hat Developer Tools software repository

First, you need to enable the Red Hat Developer Tools and Red Hat Software Collections (RHSCL) software repositories using subscription-manager:

$ su -
# subscription-manager repos --enable rhel-7-server-devtools-rpms
# subscription-manager repos --enable rhel-server-rhscl-7-rpms

Next, add the Red Hat Developer Tools key to your system. This allows yum to verify the integrity of the download packages:

# cd /etc/pki/rpm-gpg
# wget -O RPM-GPG-KEY-redhat-devel https://www.redhat.com/security/data/a5787476.txt
# rpm --import RPM-GPG-KEY-redhat-devel

2. Install the CDK

To install the CDK, run the following command as the root user:

# yum install cdk-minishift docker-machine-kvm

Note: if you intend to use VirtualBox instead of Linux KVM, you can skip the installation of docker-machine-kvm.

The CDK is a single executable, minishift, which includes a number of bundled components. You use the minishift command to start, stop, and configure the Red Hat Enterprise Linux 7 VM and the Red Hat OpenShift Container Platform single-node cluster running inside of the VM.

The oc command line tool which is used for interacting with OpenShift clusters is downloaded when you run minishift setup-cdk. The oc command must match the version of OpenShift running inside of the VM. The minishift oc-env command provides the statements to add the correct version of oc to your PATH. The output of minishift oc-env is intended to be evaluated by your shell after running minishift start.

The setup steps are:

1. Run minishift setup-cdk to set up your CDK environment in ~/.minishift
2. Add your Red Hat Developer Program username to your environment

1. Run minishift setup-cdk

Run minishift setup-cdk to setup the components needed to run CDK on your system. By default, minishift setup-cdk places CDK content in ~/.minishift.

$ 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.11.43/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, htpasswd-identity-provider, eap-cd installed
Default add-ons anyuid, admin-user, xpaas enabled
CDK 3 setup complete.

Note: If you would like to use a different directory see Environment Variables in the CDK Getting Started Guide.

If you delete ~/.minishift, you will need to run this step again.

2. Add your Red Hat Developer Program username to your environment

The VM needs to register with Red Hat to download and build container images. Add your Red Hat Developer Program username to your environment to avoid the need to enter it each time you start minishift. Your password is stored in the system keystore, so after you log in once, the CDK simply retrieves the password from the keystore.

The following command sets the username in the environment of the running shell. When a new command shell is started you will need to enter this command again.

$ export MINISHIFT_USERNAME='<RED_HAT_USERNAME>'

Optional: Permanently storing the username

The following command adds your username to your profile so it will be set on future logins. 

$ echo export MINISHIFT_USERNAME=$MINISHIFT_USERNAME >> ~/.bashrc

Start minishift

You are now ready to start the CDK. The minishift start command starts a Red Hat Enterprise Linux VM with an OpenShift cluster running inside.

Run minishift start

Start the VM with minishift start:

$ 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]
...
Extracting
Image pull complete
OpenShift server started.

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

You are logged in as:
    User:     developer
    Password: 

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

After minishift start completes, make a note of:

• The URL for the OpenShift cluster. Note: the IP address may change when you restart the CDK.
• The developer username.
• The admin username and default password.

To check that everything is working and view the OpenShift console use the command:

$ minishift console

This launches the URL listed above (for example: https://192.168.42.60:8443) with your default browser.  You will likely get a security warning from the browser about the certificate being from an unknown certificate authority. This is expected. You need to accept the certificate to proceed.

To open the console in another browser, you can get the URL of the console with the following command:

$ minishift console --url

Login to OpenShift using developer as the username.  Enter any text for the developer password.

Add the directory containing oc to your PATH

After the minishift VM has been started, you need to add oc to your PATH. The oc command must match the version of the OpenShift cluster that is running inside of the Red Hat VM. The following command sets the correct version dynamically by running minishift oc-env and parsing the output.

$ eval $(minishift oc-env)

Stopping minishift and the CDK life-cycle

You can stop the minishift VM with the command:

$ minishift stop

You can restart it again with:

$ minishift start

If necessary, you can delete the VM to start over with a clean VM using:

$ minishift delete

You won't need to run minishift setup-cdk again unless you delete the contents of ~/.minishift. You can learn more in the CDK life-cycle section of the CDK Getting Started Guide.

Build your first app

Follow these instructions to create and deploy a Node.js "Hello, World" application on OpenShift running inside the CDK using the OpenShift Web Console.

Where to go next?

• Learn more about CDK from the CDK Getting Started Guide
• If you are new to OpenShift, try the online tutorials at learn.openshift.com
• Read the OpenShift documentation
• Follow the Red Hat Developers Blog for articles on OpenShift, CDK, containers, and many other topics.

• CDK 3.7.0 for macOS  (465 MB)

Prerequisites for running the CDK on macOS

The prerequisites for running the CDK on macOS are:

• A Red Hat Developer Program username and password are required to download CDK and to enable the Red Hat Enterprise Linux VM included with the CDK to download container images from Red Hat.  Please make sure to accept the terms and conditions.

• A virtualization platform (hypervisor): Xhyve or VirtualBox.

  • For Xhyve you need to install the docker-machine-xhyve driver.

• 25 GB of free disk space.

Hypervisor

CDK includes a prebuilt Red Hat Enterprise Linux virtual machine with OpenShift and other container tools pre-installed. To run the VM a hypervisor is required.

Xhyve

Xhyve is the default hypervisor on macOS.  You will need to install the docker-machine-xhyve driver. See Set up the xhyve driver in the CDK Getting Started Guide for installation details.

VirtualBox

CDK supports VirtualBox 5.1.14 and later on all platforms. No additional downloads are required to use VirtualBox.

Since VirtualBox is not the default hypervisor, you either need to pass the command line option --vm-driver virtualbox to the minishift start command or make the setting persistent with the following command:

$ minishift config set vm-driver virtualbox

Verify the configuration setting with:

$ minishift config get vm-driver

Minishift persistent configuration is stored in the ~/.minishift directory. If you delete ~/.minishift you will need to run the commands to configure any persistent settings again. See Persistent Configuration in the CDK Getting Started Guide for more information.

The CDK download is a single executable named minishift that includes a number of bundled components. Use the minishift command to start, stop, and configure the Red Hat Enterprise Linux 7 VM and the Red Hat OpenShift Container Platform single-node cluster running inside of the VM. To run minishift commands, you need to move the minishift download to a directory that is in your command search path.

The oc command-line tool which is used for interacting with OpenShift clusters is downloaded when you run minishift setup-cdk. The oc command must match the version of OpenShift running inside of the VM. The minishift oc-env command provides the statements to add the correct version of oc to your PATH. The output of minishift oc-env is intended to be evaluated by your shell after running minishift start.

The setup steps are:

1. Copy minishift into a directory that is in your path
2. Run minishift setup-cdk. to set up your CDK environment in ~/.minishift
3. Add your Red Hat Developer Program username to your environment (starting with CDK 3.7, your password is automatically added to the system keystore the first time you log in)

Setup

Adding minishift to your path

The minishift file you downloaded in the first step is an executable. To run minishift commands, copy it to a directory that is already in your path, or create a directory and add it to the PATH environment variable. 

Copy the downloaded minishift file into ~/bin which is conventionally used as the location for executables in your home directory:

$ mkdir -p ~/bin
$ cp ~/Downloads/minishift ~/bin
$ chmod +x ~/bin/minishift

You can check if ~/bin is in your path with one of the following commands:

$ echo $PATH
$ which minishift

If you need to add ~/bin to your PATH, run the following commands to add it to your current and future login sessions:

$ echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc
$ export PATH=$PATH:$HOME/bin

Run minishift setup-cdk

Run minishift setup-cdk to setup the components needed to run CDK on your system. By default, minishift setup-cdk places CDK content in ~/.minishift.

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

Note: If you would like to use a different directory, see Environment Variables in the CDK Getting Started Guide.

If you delete ~/.minishift, you will need to run this step again.

Add Red Hat Developer Program username to your environment

The VM needs to register with Red Hat to download and build container images. You can add your Red Hat Developer Program username to your environment to avoid the need to enter it each time you start minishift. Your password is stored in the system keystore, so after you log in once, the CDK simply retrieves the password from the keystore. 

The following command sets the username in the environment of the running shell. When a new command shell is started, you will need to enter this command again.

$ export MINISHIFT_USERNAME='<RED_HAT_USERNAME>'

Optional: Permanently storing the credentials

The following command adds your username to your profile so it will be set on future logins. 

$ echo export MINISHIFT_USERNAME=$MINISHIFT_USERNAME >> ~/.bash_profile

Start minishift

You are now ready to start the CDK. The minishift start command starts a Red Hat Enterprise Linux VM with an OpenShift cluster running inside.

Run minishift start

Start the VM with minishift start:

$ 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]
...
Extracting
Image pull complete
OpenShift server started.

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

You are logged in as:
    User:     developer
    Password: 

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

After minishift start completes, make a note of:

• The URL for the OpenShift cluster. Note: the IP address may change when you restart the CDK.
• The developer username.
• The admin username and default password.

To check that everything is working and view the OpenShift console use the command:

$ minishift console

This launches the URL listed above (for example: https://192.168.42.60:8443) in your default browser.  You will likely get a security warning from the browser about the certificate being from an unknown certificate authority. This is expected. You need to accept the certificate to proceed.

Note: The web console may not launch on some older versions of Safari. To open the console in another browser, you can get the URL of the console with the following command:

$ minishift console --url

Login to OpenShift using developer as the username.  Enter any text for the developer password.

Add the directory containing oc to your PATH

After the minishift VM has been started, add oc to your path:

$ eval $(minishift oc-env)

Stopping minishift and the CDK life-cycle

You can stop the minishift VM with the command:

$ minishift stop

You can restart it again with:

$ minishift start

If necessary, you can delete the VM in order to get a fresh start with a clean VM using:

$ minishift delete

You won't need to run minishift setup-cdk again unless you delete the contents of ~/.minishift. You can learn more in the CDK life-cycle section of the CDK Getting Started Guide.

Build your first app

Follow these instructions to create and deploy a Node.js "Hello, World" application on OpenShift running inside the CDK using the OpenShift Web Console.

Where to go next?

• Learn more about CDK from the CDK Getting Started Guide
• If you are new to OpenShift, try the online tutorials at learn.openshift.com
• Read the OpenShift documentation
• Follow the Red Hat Developers Blog for articles on OpenShift, CDK, containers, and many other topics.

• CDK 3.7.0 for Windows (463 MB)

Prerequisites for running the CDK on Windows

The prerequisites for running the CDK are:

• A Red Hat Developer Program username and password are required to download the CDK and to enable the Red Hat Enterprise Linux VM included with the CDK to download container images from Red Hat.  Please make sure to accept the terms and conditions.
• A virtualization platform (hypervisor): Hyper-V or VirtualBox.
• 25 GB of free disk space.

Hypervisor

The CDK includes a prebuilt Red Hat Enterprise Linux virtual machine with OpenShift and other container tools pre-installed. To run the VM a hypervisor is required. Please make sure that the virtualization hardware extensions (VT-x or AMD-V) are enabled in your system’s BIOS. 

Hyper-V

Hyper-V is the default virtualization platform for CDK on Windows, but must be enabled as a Windows optional feature. Hyper-V isn’t available on some versions of Windows. (VirtualBox is supported as an alternative on all versions of Windows.) Once you install Hyper-V, you must add your user account to the Hyper-V Administrators group. 

Next, create an external virtual network switch and attach it to your physical network card (wired or wireless, whichever is connected) to enable internet access for downloading container images. Either of the following commands will work. The first sets the default value of hyperv-virtual-switch, while the second uses the value for the current command only: 

C:\> minishift config set hyperv-virtual-switch "External (Wireless)"

C:\> minishift start --hyperv-virtual-switch "External (Wireless)"

Be aware that the name of the virtual switch is case sensitive. For additional information on Hypervisor configuration see Set up hypervisor on Windows in the CDK Getting Started Guide or Setting up the Hyper-V Driver in the OKD documentation. 

VirtualBox

CDK supports VirtualBox 5.1.14 and later on all platforms. No additional downloads are required to use VirtualBox.

Since VirtualBox is not the default hypervisor, you either need to pass the command line option --vm-driver virtualbox to the minishift start command or make the setting persistent with the following command:

C:\> minishift config set vm-driver virtualbox

You can verify the configuration setting with:

C:\> minishift config get vm-driver

Minishift persistent configuration is stored in the .minishift directory, which is located in your home directory. If you delete %USERPROFILE%\.minishift, you need to run the commands to configure any persistent settings again. See Persistent Configuration in the CDK Getting Started Guide for more information.

Notes for Windows users

Windows shells and environment variables

You can run the CDK using the Windows command prompt or PowerShell. Working with the CDK and minishift requires setting a number of environment variables. You may encounter CDK information that shows the syntax for the bash shell, as that syntax can be used with Linux or macOS. The syntax for setting environment variables is different for the Windows command prompt and PowerShell. There are also some differences in the quoting that is required for arguments that include spaces or special characters. If you run into problems, check that you’ve correctly set any required environment variables, verify that any variables contain the expected values with set (for the command prompt) or Get-ChildItem ENV: (for PowerShell).

When setting environment variables it is important to understand the scope of the change. Using set VARIABLE=value in the command prompt or $env:VARIABLE = value in PowerShell only affects the running shell and any processes started from that shell. When a new shell is started or the system is rebooted, the environment variable is no longer set.

Environment variable settings can be made persistent by storing them in the user’s profile as part of the registry. This can be done by using the Windows Control Panel. However, this does not affect any running processes. You must start a new command shell for those changes to become part of your runtime environment.

Adding a directory to your PATH

CDK includes two command line tools, minishift.exe and oc.exe, that need to be located in a directory that is listed in your PATH environment variable. You can temporarily add a directory to the command search path by setting the PATH environment variable in the current shell. The change only affects the running shell and any processes started from that shell. If you start a new shell, you need to change the PATH environment variable again.

To permanently change your PATH, use the Windows Control Panel. Environment variable settings are found under Control Panel -> System -> Advanced System Settings -> Environment Variables. You can also get there directly by searching for Environment Variables in the Start Menu and selecting Edit Environment Variables for Your Account. These changes do not affect any currently running shells. Close any open shells and start a new shell.

Only the directory containing minishift.exe should be permanently added to the PATH. The directory containing oc.exe can change and should be added dynamically to the running shell with minishift oc-env.

User's home directory

The CDK stores state and configuration in the .minishift sub-directory of the user’s home directory. On Windows, the path is %USERPROFILE%\.minishift, which is typically C:\user\username\.minishift. You may encounter CDK information that uses the Bash shorthand ~/ to refer to the user’s home directory, for example ~/.minishift. The Windows equivalent for ~/ is %USERPROFILE%\. Note: Using PowerShell the environment variable syntax is $env:USERPROFILE.

The CDK download is a single executable that includes a number of bundled components. Use minishift.exe to start, stop, and configure the Red Hat Enterprise Linux 7 VM and the Red Hat OpenShift Container Platform single-node cluster running inside of the VM. To run minishift commands, you need to move the minishift.exe file to a directory that is in your command search path.

The oc command line tool used for interacting with OpenShift clusters is downloaded when you run minishift setup-cdk. The oc command must match the version of OpenShift running inside of the VM.  The output of minishift oc-env command provides the statements to add the correct version of oc to your PATH. 

The setup steps are:

1. Add minishift.exe to your path
2. Run minishift setup-cdk to set up your CDK environment
3. Add your Red Hat Developer Program username to your environment

Setup

Add minishift.exe to your path

The minishift.exe file you downloaded in the first step is an executable. To run minishift commands, copy it to a directory that is in already in your PATH, or create a directory and add it to the PATH environment variable. The directory must be on your system (C:\) drive. 

For the Windows command prompt: 

C:\> mkdir %USERPROFILE%\bin
C:\> copy %USERPROFILE%\Downloads\minishift.exe %USERPROFILE%\bin\minishift.exe

For PowerShell:

PS C:\> mkdir $env:USERPROFILE\bin
PS C:\> copy $env:USERPROFILE\Downloads\minishift.exe $env:USERPROFILE\bin\minishift.exe

if the directory isn’t already in your PATH, use the Windows Control Panel to update your PATH environment variable. Note: You need to start a new shell window for the change to take effect. See Windows Shells and Environment Variables above for more information.

Run minishift setup-cdk to set up your CDK environment

Run minishift setup-cdk to setup the components needed to run CDK on your system. By default, minishift setup-cdk places CDK content in %USERPROFILE%\.minishift.

C:\> minishift setup-cdk
Setting up CDK 3 on host using 'C:\Users\username\.minishift' as Minishift's home directory 
Copying minishift-rhel7.iso to 'C:\Users\username\.minishift\cache\iso\minishift-rhel7.iso' 
Copying oc.exe to 'C:\Users\username\.minishift\cache\oc\v3.11.43\windows\oc.exe' 
Creating configuration file 'C:\Users\username\.minishift\config\config.json' 
Creating marker file 'C:\Users\username\.minishift\cdk' 
Default add-ons anyuid, admin-user, xpaas, registry-route, che, htpasswd-identity-provider, eap-cd installed 
Default add-ons anyuid, admin-user, xpaas enabled 
CDK 3 setup complete.

Note: To use a different directory, see Environment Variables in the CDK Getting Started Guide. 

If you delete %USERPROFILE%\.minishift, you will need to run this step again.

Add your Red Hat Developer Program username to your environment

The VM needs to register with Red Hat to download and build container images. You can add your Red Hat Developer Program username to your environment to avoid the need to enter it each time you start minishift. Your password is stored in the system keystore, so after you log in once, the CDK uses the username from the environment variable and retrieves the password from the keystore. 

The following command sets the username in the environment of the running shell. When a new command shell is started, you will need to enter this command again.

For the Windows command prompt

C:\> set MINISHIFT_USERNAME=<RED_HAT_USERNAME>

For PowerShell

PS> $env:MINISHIFT_USERNAME='<RED_HAT_USERNAME>'

Optional: Permanently storing the credentials

You can permanently store environment variables in the registry using the Windows Control Panel. After that, when you start a new command shell the environment variables are automatically set. You will need to start a new command shell for the change to take effect.

Start the CDK

You are now ready to start the CDK. The minishift start command starts a Red Hat Enterprise Linux VM with an OpenShift cluster running inside.

Run minishift start

C:\> 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]
...
Extracting
Image pull complete
OpenShift server started.

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

You are logged in as:
    User:     developer
    Password: 

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

After minishift start completes, make a note of:

• The URL for the OpenShift cluster. Note: the IP address may change when you restart CDK.
• The developer username.
• The admin username and default password.

To check that everything is working and view the OpenShift console use the command:

C:\> minishift console

This launches the OpenShift web console (for example: https://192.168.42.60:8443) in your default browser.  You will likely get a security warning from the browser about the certificate being from an unknown certificate authority. This is expected. You will need to accept the certificate to proceed.

Note: If you prefer to use a different browser, you can get the URL of the console with the following command:

C:\> minishift console --url

Login to OpenShift using developer as the username.  Enter any text for the developer password.

Add the directory containing oc.exe to your PATH

After the minishift VM has been started, add oc to your path:

For the command prompt:

C:\> @FOR /f "tokens=*" %i IN ('minishift oc-env') DO @call %i

For PowerShell:

PS C:\> & minishift oc-env | Invoke-Expression

Stopping minishift and the CDK life-cycle

You can stop the minishift VM with the command:

C:\> minishift stop

You can restart it again with:

C:\> minishift start

If necessary, you can delete the VM in order to get a fresh start with a clean VM using:

C:\> minishift delete

You won't need to run minishift setup-cdk again unless you delete the contents of %USERPROFILE%/.minishift. You can learn more in the CDK life-cycle section of the CDK Getting Started Guide.

Build your first app

Follow these instructions to create and deploy a Node.js "Hello, World" application on OpenShift running inside the CDK using the OpenShift Web Console.

Where to go next?

• Learn more about CDK from the CDK Getting Started Guide
• If you are new to OpenShift, try the online tutorials at learn.openshift.com
• Read the OpenShift documentation
• Follow the Red Hat Developers Blog for articles on OpenShift, CDK, containers, and many other topics.