Red Hat Container Development Kit was designed to let you do your container development using the same computer on which you do your other work. CDK can be installed on the following systems:

See the CDK installation procedure for each system for more detailed hardware and software requirements.

Red Hat CDK software is available from the Red Hat Customer Portal to anyone with a valid Red Hat Enterprise Linux Developer Subscription or Developer Suite. Joining the Red Hat Developers program provides a path to getting the CDK. See the "Using the Red Hat CDK" chapter for details about Red Hat subscriptions and registration.

This guide provides the following instructions for installing and using the Red Hat CDK to begin developing containerized applications:

The rest of this book describes how to do those things.

Once the Red Hat Enterprise Linux 7 virtual machine from the Red Hat CDK is running on your chosen system, you can begin exploring the contents. Some services and tools run automatically when you boot up the virtual machine while others will require some configuration. Here is a list of some of those features:

While this document gives you the basics for installing and initially connecting to the features in your Red Hat CDK virtual machine, you should refer to other documentation for more in-depth descriptions for working with the CDK. For example:

Regardless of which platform you choose as the workstation for using CDK, you will use Vagrant to start and manage it. There are a few things you should know about Vagrant before you get started:

While this guide contains separate chapters for installing on Microsoft Windows, Mac OS X, and Linux systems, some of the components and steps are the same for all installation types. For example, the Red Hat Developer Tools ZIP file you download includes Vagrantfiles that are used on all platforms. Likewise, Vagrant boxes you use are tied to the hypervisor (such as VirtualBox or Libvirt), rather than the operating system. The installation and use of Vagrant plugins is also the same on all operating systems.

Now that you understand the basics of what is inside CDK, choose from one of the next chapters to learn how to obtain CDK and install it on a Microsoft Windows, Mac OS X, Red Hat Enterprise Linux, or Fedora system.

To run the CDK on a Microsoft Windows system, you will need:

Vagrant is used to run a Red Hat Enterprise Linux virtual machine with all necessary components for CDK. Virtualization is provided by installing VirtualBox.

Please note that Vagrant is strictly command-line oriented. All interaction with Vagrant is through the command line from a command prompt. Vagrant does not install any Start Menu entries or desktop shortcuts. You must launch PowerShell, cmd.exe or other shell to run Vagrant.

Command-line instructions use path names with a tilde, such as ~/cdk. This is a shorthand notation for a path relative to the current user’s home directory, C:\User\<username>\cdk. The %USERPROFILE% environment variable contains the Windows path to the user’s home directory and is the equivalent to ~/ in Linux.

# Cygwin Rsync under CMD.EXE Workaround
ENV["VAGRANT_DETECTED_OS"] = ENV["VAGRANT_DETECTED_OS"].to_s + " cygwin"

$ setx VAGRANT_DETECTED_OS cygwin

export VAGRANT_DETECTED_OS=cygwin

With the Vagrant box and Vagrantfiles in place, you are ready to bring up the selected Vagrant box. Your choices of Vagrantfiles are as follows:

NOTE: Instead of using one of the provided Vagrantfiles, you can copy one of the existing Vagrantfiles and modify it for your own purposes. For example, you might want to use a different IP address if it conflicts with an address on your local network.

Follow these instruction to start up a VM from the selected VM, from the proper Vagrantfile provided in the Red Hat Container Tools ZIP file.

In order to run the following steps, you need to have ssh.exe and rsync.exe in your path from installing Cygwin (or your choice of Linux-like utilities). You can temporarily add it for the current cmd.exe using the following command. If you go this route, you will need to do this every time you start a cmd.exe shell for use with Vagrant.

C:> PATH=%PATH%;C:\cygwin64\bin;

To add this location to your PATH permanently (for example, on a Windows 10 system), right click and select start → system → advanced system settings → Environment variables. Then change the PATH variable as shown.

You also need to have edited the %USERPROFILE%\.vagrant.d\Vagrantfile file as discussed in the section Translating Windows Paths and rsync.

To use an existing Vagrantfile, go to the directory with the Vagrantfile you wish to use, and start the Red Hat Enterprise Linux CDK Vagrant box by running the vagrant up command from there. Two different Vagrantfiles are provided in the Red Hat Container Tools ZIP file for the following use cases.

At this point, if all is going well, you are asked for a username and password for Red Hat Subscription Management in order to register the system and enable downloading from Red Hat repositories. You have the choice of:

To register your system now, enter the username and password you use with the Red Hat Customer Portal.

==> default: Registering box with vagrant-registration…
    default: Would you like to register the system now (default: yes)? [y|n] y
    default: Subscriber username: <username>
    default: Subscriber password:

You can check whether your Vagrant box is running using the vagrant status command. Note that you must be in the same directory where your Vagrant file is located. For example, to check the status of the rhel-ose VM, type the following:

$ cd %USERPROFILE%\cdk\components\rhel\rhel-ose
$ vagrant status

If the machine state shows as running, you are ready to start using your CDK. Refer to the following:

To run the CDK on a Mac OS X system, you need:

Vagrant is used to run a Red Hat Enterprise Linux virtual machine with all necessary components for CDK. Virtualization is provided by installing VirtualBox.

Please note that Vagrant is strictly command-line oriented. All interaction with Vagrant is through the command line from a Terminal prompt. You should use Terminal.app from the Applications → Utilities folder or a terminal emulator of your choice for running Vagrant.

Command-line instructions use path names with a tilde, such as ~/cdk. This is a shorthand notation for a path relative to the current user’s home directory, /Users/username/cdk.

With the Vagrant box and Vagrantfiles in place, you are ready to bring up the selected Vagrant box. Your choices of Vagrantfiles are as follows:

NOTE: Instead of using one of the provided Vagrantfiles, you can copy one of the existing Vagrantfiles and modify it for your own purposes. For example, you might want to use a different IP address if it conflicts with an address on your local network.

Follow these instruction to start up a VM from the selected VM, from the proper Vagrantfile provided in the Red Hat Container Tools ZIP file.

At this point, if all is going well, you are asked for a username and password for Red Hat Subscription Management in order to register the system and enable downloading from Red Hat repositories. You have the choice of:

To register your system now, enter the username and password you use with the Red Hat Customer Portal.

==> default: Registering box with vagrant-registration…
    default: Would you like to register the system now (default: yes)? [y|n] y
    default: Subscriber username: <username>
    default: Subscriber password:

You can check whether your Vagrant box is running using the vagrant status command. Note that you must be in the same directory where your Vagrant file is located. For example:

$ cd ~/cdk/components/rhel/rhel-ose/
$ vagrant status

If the machine state shows as running, you are ready to start using your CDK. Refer to the following:

To run the CDK on a Fedora or Red Hat Enterprise Linux system, you need:

Vagrant is used to run a Red Hat Enterprise Linux virtual machine with all necessary components for CDK included in it. Virtualization will be provided by using the native Linux Kernel-based Virtual machine (KVM) hypervisor and libvirt, an API and a set of tools for managing virtual machines.

A Vagrant plugin is installed to enable using libvirt as one of Vagrant virtualization providers. If you are not familiar with KVM and libvirt, see the Fedora Virtualization Getting Started Guide.

You need root privilege to install the necessary software and perform configuration on your Fedora or Red Hat Enterprise Linux development host. Once Vagrant and libvirt are installed and correctly configured, you will complete the preparation as a regular, non-root user. You will be able to start, stop, and configure Vagrant boxes using your regular user account.

Take care to use the same user ID for running Vagrant. Since Vagrant stores configuration components, such as plugins and downloaded box images, in the user’s home directory (~/.vagrant.d), if you change to a different user ID, you will need to repeat the steps that install Vagrant plugins and boxes.

Do not run Vagrant when you are logged in as the root user, to avoid creating problems with file permissions.

The remaining steps should be performed under your regular non-root user ID. This should be the same user ID you added to the vagrant group.

With the Vagrant box and Vagrantfiles in place, you are ready to bring up the selected Vagrant box. Your choices of Vagrantfiles are as follows:

NOTE: Instead of using one of the provided Vagrantfiles, you can copy one of the existing Vagrantfiles and modify it for your own purposes. For example, you might want to use a different IP address if it conflicts with an address on your local network.

Follow these instruction to start up a VM from the selected VM, from the proper Vagrantfile provided in the Red Hat Container Tools ZIP file.

At this point, if all is going well, you are asked for a username and password for Red Hat Subscription management in order to register the system and enable downloading of RPM software packages from Red Hat repositories. You have the choice of:

To register your system now, enter the username and password you use with the Red Hat Customer Portal.

==> default: Registering box with vagrant-registration…
    default: Would you like to register the system now (default: yes)? [y|n] y
    default: Subscriber username: <username>
    default: Subscriber password: *******

You can check whether your Vagrant box is running using the vagrant status command. Note that you must be in the same directory where your Vagrant file is located.

$ cd ~/cdk/components/rhel/rhel-ose/
$ vagrant status

If the machine state shows as running, you are ready to start using your CDK. Refer to the following:

The OpenShift (rhel-ose) Vagrantfile is the recommended one for container development with the Red Hat Enterprise Linux CDK. When you run vagrant up from the rhel-ose directory, the Vagrantfile starts up a Red Hat Enterprise Linux virtual machine from the vagrant box you installed. The characteristics of that box are as follows:

If you haven’t started it already, to start the CDK Red Hat Enterprise Linux VM from the rhel-ose Vagrantfile and start using it, do the following:

The next sections step you through using the different interfaces to OpenShift.

When you run vagrant up from the rhel-k8s-singlenode-setup directory, the Vagrantfile starts a Red Hat Enterprise Linux virtual machine from the vagrant box you installed. The characteristics of that box are as follows:

The resulting virtual machine is ready to start using the kubectl command to build Kubernetes pods, services, replication controllers and other features.

The docker and oc commands, which can be used to control the Docker and OpenShift services respectively, are included in CDK, which allows you to run those commands directly when you are logged into the CDK virtual machine.

The docker and oc client commands can also be used on your host system to interact with the Docker and OpenShift services running inside the CDK virtual machine. For instructions on how to install and use these commands on Microsoft Windows, Mac OS X, and Linux, see the Using the Docker Service and Using OpenShift Enterprise chapters in the CDK Getting Started Guide.

You can access the Docker service runnning on the CDK Red Hat Enterprise Linux VM from an Eclipse IDE running on your local system. Here’s how:

You can now begin using the Eclipse Docker Tooling screen to work with Docker images from inside the CDK’s virtual machine.

There are several ways you can gain access to the virtual machines you start up with your CDK. There are Vagrant commands you can use to gain shell access to a VM. Likewise, there are ways of accessing a CDK VM from Web UIs, such as OpenShift and Eclipse. The following section documents how to access your CDK VM from Vagrant.

$ vagrant list-commands

$ vagrant ssh

$ vagrant halt

$ vagrant destroy

$ vagrant global-status

With the vagrant-service-manager plugin, you can display and import environment variables needed to access the Docker, Kubernetes, and OpenShift features inside of your Vagrant CDK Red Hat Enterprise Linux VM from the desktop system. Here are examples of how to see and use that information:

$ cd $HOME/cdk/components/rhel/misc/rhel-k8s-singlenode-setup/
$ vagrant service-manager env docker
    # Copying TLS certificates to /home/chris/cdk/components/rhel/misc/rhel-k8s-singlenode-setup/.vagrant/machines/default/libvirt/docker
    # Set the following environment variables to enable access to the
    # docker daemon running inside of the vagrant virtual machine:
    export DOCKER_HOST=tcp://192.168.121.160:2376
    export DOCKER_CERT_PATH=/home/chris/cdk/components/rhel/misc/rhel-k8s-singlenode-setup/.vagrant/machines/default/libvirt/docker
    export DOCKER_TLS_VERIFY=1
    export DOCKER_MACHINE_NAME=be03562
    # run following command to configure your shell:
    # eval "$(vagrant service-manager env docker)"

In the above example, you can see that the Docker service is exposed from the IP address 192.168.121.160:2376 and TCP port 2376. A docker command or Eclipse IDE platform running on the local desktop could use that information to connect to the Docker service inside the VM. To have those values actually set inside your current shell, type the following:

$ cd $HOME/cdk/components/rhel/misc/rhel-k8s-singlenode-setup/
$ eval "$(vagrant service-manager env docker)"

To see useful information to provide manually to the oc command or OpenShift Web UI on the host, you can use the vagrant-service-manager plugin as follows:

$ cd $HOME/cdk/components/rhel/rhel-ose/
$ vagrant service-manager env openshift
   # You can access the OpenShift console on: https://192.168.121.122:8443/console
   # To use OpenShift CLI, run: oc login https://192.168.121.122:8443

So you would type https://192.168.121.122:8443/console into the location box in your web browser to access the OpenShift Web UI from your desktop. Run oc login https://192.168.121.122:8443 from the command line on your desktop to connect to the OpenShift service with the oc command.

With the vagrant-registration plugin, you can manage the Red Hat subscriptions for your Red Hat Enterprise Linux VMs through Vagrant. The plugin is capable of managing subscriptions with the type of subscription service that is available on the guest. However, at the moment it supports only Red Hat Enterprise Linux Suscription Manager (subscription-manager and related commands) and the older rhn_register command.

If you did not register your Red Hat Enterprise Linux VM when you started it with vagrant up, you should register it now. Registering your Red Hat Enterprise Linux system is highly recommended. Until you register, you cannot use the official Red Hat repositories to:

Red Hat Enterprise Linux base container images are configured to have Docker use the credentials of the host system. So when you try to install packages inside of a container, the yum command uses the host credentials to gain access to those packages from Red Hat. Without a valid Red Hat subscription, you will not have a fully-functioning setup for building Red Hat Enterprise Linux containers.

The process of registering your CDK virtual machine with Red Hat is automated using a Vagrant plugin, vagrant-registration. By default, when a Vagrant box is started, you are prompted to enter your username and password for the Red Hat Customer Portal. The registration plugin automatically attaches the Vagrant box to an available subscription.

When a Red Hat Enterprise Linux VM is registered in the CDK, an identity and time-limited entitlement is created for that VM. Once it is registered, the VM does not need to be re-registered until the CDK entitlement expires. Once the time limit is up, that container loses access to the Red Hat software repositories (CDN).

You can register your CDK system with a valid Red Hat Enterprise Linux Developer Subscription or Developer Suite. Joining the Red Hat Developers program provides a path to getting the CDK. Once you register a CDK VM, you get a new entitlement that lasts for 90 days that does not come out of your pool. If you re-register the same VM, you will get a new 90 day entitlement. You can do this over and over.

There are a few things you should know about releasing a subscription:

If you do not have a Red Hat Enterprise Linux subscription, there are plans in the works to offer free entitlements to the Red Hat Enterprise Linux Developer Suite. Those entitlements will let you download and register a Red Hat Enterprise Linux host in the CDK. Keep an eye on the Red Hat Developer’s site for details.

Vagrant.configure('2') do |config|
 config.registration.username = '<your Red Hat username>'
 config.registration.password = '<your Red Hat password>'
end

Vagrant.configure('2') do |config|
  config.registration.username = ENV['SUB_USERNAME']
  config.registration.password = ENV['SUB_PASSWORD']
end

The vagrant-sshfs plugin allows you to mount a folder from your host system inside the CDK virtual machine for the purpose of sharing files between those two environment. The shared file system relies on the SSH File Tranfer Protocol for sharing files. Although this is not the fastest or most efficient for file sharing today, the common availability of the SSH service makes this a popular way to share files between systems that don’t require high volume of file copies between systems.

The vagrant-sshfs plugin works on all systems supported by the CDK (Windows, Mac, Fedora, and Red Hat Enterprise Linux). It also integrates with all CDK-supported virtualization technologies (Virtualbox and Libvirt). Here are the steps for configuring the vagrant-sshfs plugin to share files between your CDK host system and a CDK virtual machine running on that host.

For more details on how to configure the vagrant-sshfs service, refer to the vagrant-sshfs GitHub documentation.