-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat Container Development Kit
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
- The Red Hat Container Development Kit 3.3 Release Notes and Known Issues contains information about the current release of the product as well as a list of known problems that users may encounter when using it.
- The Container Development Kit Getting Started Guide contains instructions on how to install and start using the Container Development Environment to develop Red Hat Enterprise Linux-based containers using tools and services such as OpenShift Container Platform, Docker, Eclipse, and various command line tools.
- Report issues with Red Hat Container Development Kit or request new features using the CDK project at https://issues.jboss.org/projects/CDK.
- Report issues with the Red Hat Container Development Kit 3.3 Release Notes and Known Issues and Container Development Kit Getting Started Guide using the RHDEVDOCS project at https://issues.jboss.org/projects/RHDEVDOCS.
1.2. Preparing to Install Container Development Kit
1.2.1. Overview
Container Development Kit 3.3 is based on Minishift 1.11.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.
CDK version 2.x was based on Vagrant. Because of the completely different deployment and management methods, there is no upgrade path from CDK 2.x to CDK 3.x versions. You need to do a fresh setup.
The following section describes how to install CDK and the required dependencies.
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 (as described in the coming setup procedure).
Depending on your host operating system, you have the choice of the following hypervisors:
- macOS
- xhyve (default)
- VirtualBox
- Red Hat Enterprise Linux
- KVM (default)
- VirtualBox
- Windows
- Hyper-V (default)
- VirtualBox
Refer to the documentation for each hypervisor to determine the hardware and operating system versions needed to run that hypervisor.
1.2.3. Understanding CDK Installation
These are the basic steps for setting up CDK on your personal laptop or desktop system:
- Set up your virtualization environment
- Download CDK software for your operating system from the Red Hat Container Development Kit Download Page
- Set up CDK
- Start CDK
- Configure CDK so you can use it efficiently
1.3. CDK Installation
1.3.1. Installing CDK
The following steps describe how to prepare your virtualization environment (hypervisor) for CDK, download CDK software, set up CDK, and start using it.
1.3.2. Step 1: Set up your virtualization environment
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.
1.3.2.1. Set up hypervisor on Red Hat Enterprise Linux
Choose between KVM (default) and VirtualBox for your hypervisor. Manual driver setup is required for KVM. The driver is automatically configured if you install VirtualBox. However, a minishift
command will be required later to identify VirtualBox to CDK.
On Red Hat Enterprise Linux with KVM virtualization:
CDK is currently tested against docker-machine-driver-kvm
version 0.10.0. Follow these steps to install the KVM driver and configure your user account to use the libvirtd service.
As root, install the KVM binary and make it executable as follows:
# curl -L https://github.com/dhiltgen/docker-machine-kvm/releases/download/v0.7.0/docker-machine-driver-kvm -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.
As root, install libvirt and qemu-kvm on your system and add yourself to the libvirt group:
# yum install libvirt qemu-kvm # usermod -a -G libvirt <username>
Update your current user session to apply the group change:
$ newgrp libvirt
Start the libvirtd service as root:
# systemctl start libvirtd # systemctl enable libvirtd
1.3.2.2. Set up hypervisor on macOS
Choose between xhyve (default) and VirtualBox for your hypervisor. Manual driver setup is required for xhyve. The driver is automatically configured if you install VirtualBox. However, a minishift
command option (--vm-driver virtualbox
) will be required later to identify VirtualBox to CDK.
On macOS with xhyve virtualization:
CDK on macOS with xhyve virtualization is currently tested against docker-machine-driver-xhyve
version 0.3.3. To manually install the xhyve driver, you need to download and install the docker-machine-driver-xhyve
binary and place it in a directory which is on your PATH
environment variable. The directory /usr/local/bin is most likely 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-xhyve
binary to the /usr/local/bin/ directory:
Download the
docker-machine-driver-xhyve
binary using:$ sudo curl -L https://github.com/zchee/docker-machine-driver-xhyve/releases/download/v0.3.3/docker-machine-driver-xhyve -o /usr/local/bin/docker-machine-driver-xhyve
Enable root access for the
docker-machine-driver-xhyve
binary and add it to the default wheel group:$ sudo chown root:wheel /usr/local/bin/docker-machine-driver-xhyve
Set owner User ID (SUID) for the binary as follows:
$ sudo chmod u+s,+x /usr/local/bin/docker-machine-driver-xhyve
The downloaded docker-machine-driver-xhyve
binary is compiled against a specific version of macOS. It is possible that the driver fails 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/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
For more information, see the xhyve driver documentation on GitHub.
1.3.2.3. Set up hypervisor on Windows
Choose between Hyper-V (default on Windows 10) and VirtualBox (Windows 7 or Windows 10) for your hypervisor. Manual driver setup is required for Hyper-V. The driver is automatically configured if you install VirtualBox. However, a minishift
command option (--vm-driver virtualbox
) will be required later to identify VirtualBox to CDK.
On Windows with Hyper-V virtualization:
- Install Hyper-V.
- Add an External Virtual Switch. Ensure that you pair the virtual switch with a network card (wired or wireless) that is connected to the network.
Set the environment variable
HYPERV_VIRTUAL_SWITCH
to the name of the external virtual switch you want to use for CDK. For more information, see driver-specific environment variables.For example, on Command Prompt use:
C:\> set HYPERV_VIRTUAL_SWITCH=External (Wireless)
Note that using quotes in Command Prompt results in the following error:
C:\> set HYPERV_VIRTUAL_SWITCH="External (Wireless)" Error creating the VM. Error with pre-create check: "vswitch \"\\\"External (Wireless)\\\"\" not found"
However, on PowerShell you need to use the quotes:
PS C:\> $env:HYPERV_VIRTUAL_SWITCH="External (Wireless)"
1.3.3. Step 2: Download CDK Software
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.3.0-1-minishift-darwin-amd64
(for macOS), cdk-3.3.0-1-minishift-linux-amd64
(for Linux) or cdk-3.3.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.3.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.3.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.
This directory must be on the C:\ drive!
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).
1.3.4. Step 3: Set 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).
To use a directory other than ~/.minishift, you must set the --minishift-home
flag and 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.7.14/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 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.3.5. Step 4: Start CDK
- If you have set up VirtualBox as your hypervisor, you need to configure the VirtualBox driver.
- Skip this step if you are using the default hypervisor for your operating system (KVM for Linux, xhyve for macOS, or Hyper-V for Windows).
Use one of the following two methods to switch the hypervisor used by CDK to VirtualBox:
-
Temporary: Add the
--vm-driver virtualbox
flag to theminishift start
command to use VirtualBox immediately. -
Persistent: To persistently change the hypervisor, run the
minishift config set vm-driver virtualbox
command. See the Persistent Configuration section for examples.
-
Temporary: Add the
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.
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 tominishift 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 as shown here: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
-
Skip registration: Add the
Run
minishift start
to set up and start the virtual machine with the default configuration. See theminishift start
command reference for more options to modifyminishift start
. The following is an example of how that would look when run on a Red Hat Enterprise Linux system:$ 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: <any value> To login as administrator: oc login -u system:admin ...
Run the following command to check the status of the virtual machine:
$ minishift status Running
You will see similar output from minishift start
when run in a macOS terminal or Windows command prompt or PowerShell.
1.3.6. Step 5: Configure CDK
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.
oc
: Useminishift oc-env
to display the command you need to type into your shell in order to add theoc
binary to yourPATH
environment variable. The output ofminishift oc-env
will differ depending on your user directory, operating system and shell type.For Red Hat Enterprise Linux:
$ minishift oc-env export PATH="/home/user/.minishift/cache/oc/v3.7.14:$PATH" # Run this command to configure your shell: # eval $(minishift oc-env)
Use the following to add the
oc
command to yourPATH
via the ~/.bashrc file:$ echo export PATH=\"/home/user/.minishift/cache/oc/v3.7.14:\$PATH\" >> ~/.bashrc $ source ~/.bashrc
For macOS:
$ minishift oc-env export PATH="/home/user/.minishift/cache/oc/v3.7.14:$PATH" # Run this command to configure your shell: # eval $(minishift oc-env) $ echo export PATH=/Users/user/.minishift/cache/oc/v3.7.14:\$PATH >> ~/.bash_profile $ source ~/.bash_profile
For Windows:
Add the path to the
oc
binary to yourPATH
environment variable.
For more information about interacting with OpenShift from the command line interface, see the OpenShift Client Binary section.
OpenShift web console: To access OpenShift from the web console, you can either:
-
Run
minishift console
to open the OpenShift web console from your default browser or -
Open a browser to the URL output from the
minishift start
command (for example, https://192.168.42.60:8443).
From the web console screen, enter the user name (developer) and password (developer) displayed from the output.
-
Run
You are now ready to start using OpenShift using either of those two interfaces.
1.3.7. Deploying a Sample Application
OpenShift provides various sample applications, such as templates, builder applications, and quickstarts. To begin creating an application, see:
-
Creating an Application Using the CLI to use the
oc
command to create a new application. - Creating an Application Using the Web Console to use the OpenShift web user interface to create applications.
The following steps describe how to deploy a sample Node.js application from the command line.
Create a Node.js example application:
$ oc new-app https://github.com/openshift/nodejs-ex -l name=myapp
Track the build log until the application is built and deployed:
$ oc logs -f bc/nodejs-ex
Expose a route to the service:
$ oc expose svc/nodejs-ex
Access the application:
$ minishift openshift service nodejs-ex --in-browser
If you are done with the VM, use
minishift stop
to stop the VM temporarily. You can return to the same state later withminishift start
.$ minishift stop Stopping local OpenShift cluster... Stopping "minishift"...
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.
1.4. Uninstalling CDK
1.4.1. Overview
This section describes how you can uninstall the minishift
binary and delete associated files.
1.4.2. Uninstalling CDK
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.
To completely uninstall CDK, delete everything in the MINISHIFT_HOME directory (default ~/.minishift) and ~/.kube:
For Red Hat Enterprise Linux and macOS:
$ rm -rf ~/.minishift $ rm -rf ~/.kube
For Windows PowerShell:
Replace
<MINISHIFT_HOME>
with the location of your home directory.PS C:\> Remove-Item -Recurse -Force C:\<MINISHIFT_HOME>\.minishift\ PS C:\> Remove-Item -Recurse -Force C:\<MINISHIFT_HOME>\.kube\
For Windows command prompt:
Replace
<MINISHIFT_HOME>
with the location of your home directory. (You may need to use thedel /s
command instead.)c:\> rm -r c:\<MINISHIFT_HOME>\.minishift c:\> rm -r c:\<MINISHIFT_HOME>\.kube
-
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.