Red Hat Training

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

Chapter 3. Installing Container Development Kit on Microsoft Windows

Note

The preferred way to install Container Development Kit on Microsoft Windows is to use the all-in-one installer, which is provided by Red Hat Development Suite. See the Red Hat Development Suite Installation Guide for detailed information. To proceed with a manual installation procedure, follow the instruction in this section.

To prepare your Microsoft Windows development system to run the Container Development Kit, the steps are:

  1. Download and install Cygwin.
  2. Download and install VirtualBox or enable Hyper-V.
  3. Download and install Vagrant.
  4. Download Red Hat Container Tools and the Container Development Kit Vagrant box for VirtualBox or Hyper-V.
  5. Install additional Vagrant plugins to support Red Hat Subscription Management and other features.

3.1. Prerequisites for Installing Container Development Kit on Microsoft Windows

To run the Container Development Kit on a Microsoft Windows system, you 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.
  • Adequate Internet connectivity to download 1—​2 GB of software.
  • An available Red Hat Enterprise Linux Server subscription. Note that Red Hat Enterprise Linux subscriptions with self-support do not have access to all of the necessary software for Container Development Kit in all environments.
  • 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.

3.2. Installing Software and Configuring the Host System

This chapter describes installation and configuration of software prerequisities for running the Container Development Environment.

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.

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

When rsync synchronization has been specified, Vagrant does not start if rsync.exe is not in the path.

3.2.1.1. Installing Cygwin

Download and install Cygwin from the Cygwin Installation page. Cygwin installation adds ssh.exe and rsync.exe to your path.

To temporarily add the Cygwin path for the current cmd.exe session, use the following command. 

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

To add this location to your path permanently on a Microsoft Windows 10 system, right-click on the desktop and select Start → System → Advanced system settings → Environment variables. Then change the PATH variable as shown.

3.2.1.2. Installing and Enabling Hyper-V

Important

Please, note that Hyper-V support in the Red Hat Container Development Kit 2.2 product has been released as Technical Preview. This impacts the level of support offered by Red Hat. For additional information, please, see Technology Preview Features Support Scope.

  1. Install and enable Hyper-V support by following instructions at Install Hyper-V on Windows 10.
  2. Add a Virtual Switch using the Hyper-V Manager by following instructions at Create a Virtual Switch.

3.2.1.3. Installing VirtualBox

Download and install VirtualBox for Microsoft Windows from virtualbox.org.

Important

Container Development Kit 2.2 is known to not work correctly with VirtualBox 5.1.x. If you intend to use VirtualBox as your virtualization provider, and you already have VirtualBox 5.1.x installed, downgrade your installation to VirtualBox 5.0.26.

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 default location for VirtualBox images, 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 that the Start Menu entry for VirtualBox is Oracle VM VirtualBox.

See VirtualBox Documentation for additional information.

3.2.1.4. Installing Vagrant

Vagrant is used to run a Red Hat Enterprise Linux virtual machine with all necessary components for Container Development Kit. Virtualization is provided by installing VirtualBox or by enabling Hyper-V.

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 Cygwin’s Terminal Window, cmd.exe, or other shell to run Vagrant.

  1. Download and install Vagrant from https://releases.hashicorp.com/vagrant/. Select the folder with the 1.8.1 release and download the installer in the .msi format (vagrant_1.8.1.msi). The 1.7.4 version of Vagrant is also supported for use with Red Hat Container Development Kit 2.2, but 1.8.1 is necessary to use the Hyper-V hypervisor. The Vagrant installer automatically adds Vagrant to the path.
  2. Download and install Microsoft Visual C++ 2010 SP1 Redistributable Package (x86) (this is a requirement for using Vagrant 1.8.1).

3.2.1.5. Obtaining Container Development Kit Components

Downloading from the Red Hat Customer Portal

Download the Container Development Kit components from Red Hat Product Downloads. 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 Container Tools
  • RHEL 7.2 Vagrant box for VirtualBox or
  • RHEL 7.2 Vagrant box for Hyper-V
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 or Hyper-V.

Downloading through the Red Hat Developers Program

Alternatively, if you do not have a valid Red Hat Enterprise Linux subscription, you can obtain Container Development Kit by registering with the Red Hat Developers program. Follow the instructions at Red Hat Container Development Kit Get Started.

Download Path

The instructions in this guide assume you have saved the downloaded Container Development Kit components 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.

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

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. Using 'c:\User\joe', causes the path to be interpreted correctly.

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

3.3. Setting Up Container Development Kit 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.

  2. Install additional Vagrant plugins for using the Container Development Kit Vagrant boxes.

    All of the remaining steps can be performed using the Windows command-line shell, cmd.exe, PowerShell, 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.

    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-*.gem
C:> vagrant plugin install vagrant-service-manager-*.gem
C:> vagrant plugin install vagrant-sshfs-*.gem

  3. Verify the plugins are installed by running the following command: 

    C:> vagrant plugin list

For information on using the plugins after Container Development Kit is installed, see Using Vagrant Container Development Kit Plugins in the Container Development Kit Getting Started Guide.

  1. Add the Container Development Environment box to Vagrant. 

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

    The name you assign to the box using the --name parameter in the above step must correspond to the name used by the Vagrantfile used to initialize the box. By default, this is cdkv2 for the Vagrantfiles provided with Container Development Kit.

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

3.4. Starting the Container Development Kit Vagrant Box on Microsoft Windows

Container Development Kit offers two Vagrantfiles for initializing the Container Development Environment with different services:

  • OpenShift (rhel-ose): Use the OpenShift Vagrantfile to launch a Red Hat Enterprise Linux Server virtual machine (VM) with OpenShift Enterprise running in it. With OpenShift running, you can use either the web user interface from a web browser on your desktop, or docker, oc, and related commands by logging into the VM.
  • Kubernetes (rhel-k8s-singlenode-setup): Use the Kubernetes Vagrantfile to start a more generic Container Development Kit VM. Because OpenShift is not running, you can configure a more basic Kubernetes configuration or use Docker directly.
Note

You can modify the existing Vagrantfiles 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.

In order to run the following steps, you need to have edited the %USERPROFILE%\.vagrant.d\Vagrantfile file as discussed in the Section 3.2.2, “Translating Windows Paths and rsync” section.

  1. Initialize the Container Development Kit Vagrant box:

    • Start Container Development Kit with OpenShift Enterprise as follows: 

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

    • Start Container Development Kit with single-node Kubernetes follows: 

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

  2. Enter the username and password you use with the Red Hat Customer Portal to register the Red Hat Enterprise Linux system running in the Vagrant box: 

    ==> 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:

  3. Check whether your Vagrant box is running using the vagrant status command. Note that you must be in the same directory where your Vagrantfile is located. For example: 

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

If the machine state shows as running, you are ready to start using your Container Development Environment.

3.5. Additional Resources