Red Hat Training

A Red Hat training course is available for Red Hat Container Development Kit

Chapter 2. Installing Red Hat Container Development Kit on Microsoft Windows

To prepare your Microsoft Windows development system to run the CDK, the steps are:

  1. Download and install the VirtualBox virtualization software.
  2. Download and install Vagrant.
  3. Download Red Hat Container Tools and Vagrant boxes for Red Hat Enterprise Linux.
  4. Install additional Vagrant plugins to support Red Hat Subscription Management and other features.
Note

The version of the CDK described in this document is made to be used with VirtualBox software. It will not work if you are using other software that provides virtualization support on your Windows system. Check back later for support for other Windows virtualization environments.

2.1. Prerequisites

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

  • A 64-bit machine with a minimum of 4 GB of RAM running Windows 7 64-bit or later.
  • A minimum of 3 GB of free disk space for virtual machine images. Note that during the setup process you will need to be able to store multiple copies of each of the virtual machine images.
  • Adequate Internet connectivity to download 1—​2 GB of software.
  • An available Red Hat Enterprise Linux Server subscription with support or Red Hat Enterprise Linux Developer Suite. Note that Red Hat Enterprise Linux subscriptions with self-support do not have access to all of the necessary software for CDK in all environments. (See the Using the CDK chapter for more information on working with subscriptions in the CDK.)
  • A text editor that allows editing text files that do not have extentions, such as Vagrantfile. Ideally your text editor should be flexible about line endings as you may encounter files that only have new-lines.
  • The rsync and ssh command-line utilities need to be installed. The recommended source is the Cygwin project. If you choose to use rsync and ssh from an alternate source, there may be some path and command line incompatibilities that are not addressed in this guide.

2.2. Installing Virtualization and CDK Components on Windows

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.

2.2.1. Additional Software Requirements for Microsoft Windows

It is recommended that you install the Cygwin environment from cygwin.com to provide the ssh and rsync tools for use by Vagrant. Please note that if you choose to use ssh and rsync from a different source, you may run into some incompatibilities in command-line arguments and path names.

An SSH client is required to access Vagrant virtual machines. While a graphical utility that provides SSH, such as PuTTY, can be used, it is preferred to have an SSH client that can be run from the command line. Vagrant manages the SSH environment, allowing you to log into your Vagrant box by simply running the vagrant ssh command. For this to work, ssh must be in the Windows path.

Synchronized folder support in Vagrant uses rsync. When VirtualBox shared folders are not available or rsync synchronization has been specified, Vagrant does not start if rsync.exe is not in the path.

To install Cygwin software on your Windows system, do the following:

NOTE: As an alternative to the steps below, you could install apt-cyg from the apt-cyg page on github.com. Then you could install the required packages as follows: apt-cyg install rsync openssh

  1. Go to the Cygwin Installation page.
  2. Download and install the appropriate setup executable (for example setup-x86_64.exe).

2.2.2. Translating Windows Paths and rsync

rsync uses POSIX style path names and cannot use Windows paths that contain drive letters and backslashes directly. Cygwin uses paths that start at /cygdrive/drive-letter/ so, C:\file.exe translates to /cygdrive/c/file.exe. Other ports of Linux utilities use different conventions. For example, the MinGW/MSYS environment uses paths that start at /drive-letter, so C:\file.exe translates to /c/file.exe. Vagrant tries to detect what environment is being used and translate paths appropriately. However, there are cases where this does not work.

One way to deal with this issue is to add the following lines to the per-user Vagrantfile in the %USERPROFILE%\.vagrant.d\Vagrantfile file. Note that you will most likely need to create this file.

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

If you use Cygwin’s rsync under Windows cmd.exe, Vagrant is not able to tell that you are using Cygwin and supplies the wrong path to rsync. The workaround is to set the VAGRANT_DETECTED_OS variable to cygwin. For example:

$ setx VAGRANT_DETECTED_OS cygwin

To permanently set this variable for a bash shell, add the following line to the .bashrc file in the user’s home directory (~/.bashrc):

export VAGRANT_DETECTED_OS=cygwin

An alternative is to run Vagrant inside of Cygwin’s Terminal Window. This will provide a Linux-like experience with the Bash shell and a window that can be sized beyond 80 columns. In this way, you can use both Linux and Windows paths. However, to use Windows paths, you must surround thoses paths with single quotes. For example, c:\User\joe would be interpreted by the shell as c:Userjoe without single quotes. Surrounding 'c:\User\joe' with single quotes, causes it to be interpreted correctly.

2.2.3. Software Download and Installation to add to Windows

  1. Download and Install VirtualBox for Microsoft Windows from virtualbox.org.

    Optional: Choose a location for storing VirtualBox VM images. By default, these are stored in your home directory (~/VirtualBox VMs). You will need several gigabytes of space wherever you choose to store these images. To change the location start VirtualBox, Use the VirtualBox → Preferences → General menu, then change Default Machine Folder to the desired location. Documentation for VirtualBox can be found on the virtualbox.org website.

    Note

    The Start Menu entry for VirtualBox is Oracle VM VirtualBox.

    Documentation for VirtualBox can be found on the virtualbox.org web site.

  2. Download and install Vagrant from vagrantup.com. The download page is: Vagrant Versions. Select the folder with the latest 1.7.x release (such as 1.7.4) and download the vagrant file in .msi format (for example, vagrant_1.7.4.msi).

    Note

    For Windows, you should use the latest version of Vagrant 1.7 (for example, 1.7.4). The latest Vagrant 1.8 version does not work in this environment. Vagrant 1.7 may be required for other versions of Windows as well.

    The Vagrant installer should automatically add Vagrant to the Windows path. If it does not, add C:\HashiCorp\Vagrant\bin to the path through the Windows Control Panel.

    At this point the Vagrant installer recommends a reboot. At a minimum, you must restart your command shell to get the updated path.

  3. Download the CDK software components from the Red Hat Product Downloads web site. You must log in to get access to this page. If you are on the right page, you should see "Product Variant: Red Hat Container Development Kit". You need to download the following items:

    • Red Hat Developer Tools
    • RHEL 7.2 Vagrant box for VirtualBox

      Note

      The page also offers Vagrant box downloads formatted for other virtualization platforms, such as libvirt. You only need to download the box image that matches the virtualization you are using — VirtualBox.

The following steps assume you have saved these files in your home directory in %USERPROFILE%\Downloads. If you used a different directory, adjust the paths accordingly. You need several gigabytes of free space for the Vagrant box images.

2.3. Setting up CDK Software Components

  1. Unzip the ZIP file you downloaded in a directory of your choice. The following commands assume you have unpacked it in your home directory, %USERPROFILE%\cdk (C:\Users\<username>\cdk).

    At this point, review the included README files to familiarize yourself with Red Hat Container Tools and to be notified if there have been any changes since this installation guide was published. The README file associated with each Vagrantfile can be viewed as a plain text file. The plugin README files are are formatted in Markdown. So you might want to use a Markdown reader for a better experience with those files.

  2. Install additional Vagrant plugins for using Red Hat Vagrant boxes.

    All of the remaining steps can be performed using the Windows PowerShell, command-line shell, cmd.exe or other command line shell.

    To install additional Vagrant plugins to support several features, use the vagrant plugin install command. The plugins in the form of .gem files are included in the ZIP file.

    Note that the version number of the .gem files may have changed. You should use the file name that matches your downloaded files.

    The installation of the first plugin may take several minutes, and Vagrant may install some additional gem files as needed.

    C:> cd %USERPROFILE%\cdk\plugins
    C:> dir *.gem
    C:> vagrant plugin install vagrant-registration-1.2.1.gem
    C:> vagrant plugin install vagrant-service-manager.1.0.1.gem
    C:> vagrant plugin install vagrant-sshfs-1.1.0.gem

    Verify the plugins are installed by running the following command:

    C:> vagrant plugin list

    For information on using the plugins after the CDK is installed, see the "Managing Your Red Hat Enterprise Linux Vagrant Boxes" chapter.

  3. Add the Red Hat Enterprise Linux Server box to Vagrant.

    This is the configured virtual machine image that you downloaded in the previous step.

    C:> cd %USERPROFILE%\Downloads\
    C:> vagrant box add --name cdkv2 rhel-cdk-kubernetes-7.2*.x86_64.vagrant-virtualbox.box

    Note that if you plan on using a Vagrantfile to initialize the Vagrant box, the name you assign to the box using the --name parameter in the above step must correspond to the name used by the Vagrantfile to refer to the box. (The default is cdkv2.)

    Verify that the box is installed:

    C:> vagrant box list

    The box image files will be stored in your home directory under %USERPROFILE%\.vagrant.d. You will need adequate space there, approximately 2 GB.

2.4. Starting CDK Vagrant Box in Windows

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:

  • OpenShift (rhel-ose): The OpenShift (rhel-ose) Vagrantfile launches a Red Hat Enterprise Linux server virtual machine (VM) with OpenShift Enterprise running on it. With OpenShift running, you can use either the Web Console from the browser on your desktop or docker, oc, and related commands by logging into the VM. With some additional setup, you can add other tools to access feature in the VM from your host (see Using the CDK for information on how to to access the VM from Eclipse or command line tools from your desktop).
  • Kubernetes(rhel-k8s-singlenode-setup): Use the Kubernetes (rhel-k8s-singlenode-setup) Vagrantfile to start a more generic CDK VM. Because OpenShift is not running, you can configure a more basic Kubernetes configuration or use docker directly.

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.

Note

Before you start your CDK Vagrant box, consider reviewing the Vagrantfile to see if there are any settings you want to change. In particular, you might want to configure SSHFS to share a directory between your CDK virtual machine and your local system. See the description of the vagrant-sshfs plugin in the "Using the Red Hat CDK" chapter for information on how to configure this.

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.

Note

Before you start your CDK Vagrant box, consider reviewing the Vagrantfile to see if there are any settings you want to change. In particular, you might want to configure SSHFS to share a directory between your CDK virtual machine and your local system. See the description of the vagrant-sshfs plugin in the "Using the Red Hat CDK" chapter for information on how to configure this.

  • Start the OpenShift Enterprise integration (rhel-ose)

    $ cd %USERPROFILE%\cdk\components\rhel\rhel-ose
    $ vagrant up
  • Start the Single-node Kubernetes setup (rhel-k8s-singlenode-setup)

    $ cd %USERPROFILE%\cdk\components\rhel\misc\rhel-k8s-singlenode-setup
    $ vagrant up

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:

  • Registering your Red Hat Enterprise Linux VM now (recommended) or
  • Registering your Red Hat Enterprise Linux VM later

    NOTE: See the Using the CDK chapter for information on obtaining Red Hat Enterprise Linux subscriptions, how registration works with the CDK, and details on why you need to register your system.

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:

  • The Using the CDK chapter will help you understand the different Vagrantfiles, plugins and interfaces needed to work with your CDK. It also discusses special topics, such as other ways to register your Red Hat Enterprise Linux virtual machines.
  • The Getting Started with Container Development Kit guide provides information on getting started with container development.