Red Hat Training

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

Chapter 7. Installing Container Development Kit on Red Hat Enterprise Linux

This chapter provides instructions on how to install and configure Red Hat Container Development Kit components and dependencies on Red Hat Enterprise Linux.

7.1. Prerequisites for Installing Container Development Kit on Red Hat Enterprise Linux

To run Container Development Kit, you need:

  • A 64-bit machine with a minimum of 4 GB of RAM. At least 2 GB should be reserved for Container Development Kit, with 3—​4GB reserved for Container Development Kit being more reasonable if you plan to run multiple virtual machines. The Kubernetes Vagrantfile defines 1⁠GB of disk space while the OSE Vagrantfile asks for up to 3⁠GB of disk space.
  • 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 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.

The following steps outline the installation procedure:

  1. Enable virtualization support in your computer’s BIOS.
  2. Install the host operating system.
  3. Install the KVM and libvirt virtualization software.
  4. Install Vagrant.
  5. Download Red Hat Container Tools and the Container Development Kit Vagrant box.
  6. Install additional Vagrant plugins to support Red Hat Subscription Management and other features.
  7. Start the Vagrant box using a Vagrantfile.

If any of the steps have already been performed (such the installation of the host operating system), they do not need to be repeated.

7.2. Installing Software and Configuring the Host System

Vagrant is used to run a Red Hat Enterprise Linux virtual machine with all necessary components of Container Development Kit included in it. Virtualization is provided by using the native Linux kernel-based virtual machine (KVM) hypervisor and libvirt.

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 Red Hat Enterprise Linux Virtualization Getting Started Guide.

You need root privileges to install the necessary software and perform configuration on your development host. Once Vagrant and libvirt are installed and correctly configured, you 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. Because 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 use, to avoid creating problems with file permissions.

7.2.1. Installing Virtualization and Container Development Kit Components

The following steps need to be completed as root:

  1. If you have not already done so, install the host system directly on hardware or on a virtual machine that is set to act as a hypervisor.
  2. Make sure your host Red Hat Enterprise Linux system is registered using your Red Hat username and password.
  3. Enable required software repositories.
  4. Install and configure the libvirt virtualization environment.
  5. Install Vagrant and configure the development host for running Vagrant boxes.

7.2.1.1. Registering a Red Hat Enterprise Linux System and Enabling Repositories

  1. Register Red Hat Enterprise Linux and enable required system repositories:

    You need access to the Red Hat Software Collections (rhel-<variant>-rhscl-7-rpms) repository. See Getting Access to Red Hat Software Collections. 

    # subscription-manager register --auto-attach --username=<username> --password=<password>
# subscription-manager repos --enable rhel-<variant>-rhscl-7-rpms
# subscription-manager repos --enable rhel-7-<variant>-optional-rpms

    In the above examples, replace <variant> with server or workstation, depending on which variant of Red Hat Enterprise Linux you are using.

  2. Download and unpack the centos-release-scl package from CentOS.

    The contents of the package will be used to enable the Software Collections repository and add a GPG key to enable the checking of the validity of installed RPM packages:

    Note

    Because Vagrant is not officially packaged for Red Hat Enterprise Linux, it needs to be installed using a Software Collection packaged for CentOS. 

    ~]$ mkdir Downloads
~/Downloads]$ wget http://mirror.centos.org/centos/7/extras/x86_64/Packages/centos-release-scl-2-2.el7.centos.noarch.rpm
~/Downloads]$ rpm2cpio ./centos-release-scl-2-2.el7.centos.noarch.rpm | cpio -idmv

  3. As the root user, enable the Software Collections repository: 

    /home/joe/Downloads]# cp etc/yum.repos.d/CentOS-SCLo-scl.repo /etc/yum.repos.d/

  4. As the root user, copy the Software Collections GPG key to the directory where yum will be able to use it: 

    /home/joe/Downloads]# cp etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-SIG-SCLo /etc/pki/rpm-gpg/
  5. Update your system using yum update. If a new kernel is installed during the update, reboot your system before proceeding with the remaining steps.

7.2.1.2. Installing and Initializing Virtualization Software

  1. Install virtualization software.

    • On Red Hat Enterprise Linux Server, install the Virtualization Host package group: 

      # yum groupinstall "Virtualization Host"

    • On Red Hat Enterprise Linux Workstation, install the following package groups: 

      # yum groupinstall base, core, virtualization-hypervisor, virtualization-tools
# yum install libvirt-devel rpm-build zlib-devel ruby-devel rh-ruby22-ruby-devel gcc-c++

  2. Launch the libvirtd daemon and configure it to start at boot, run: 

    # systemctl start libvirtd
# systemctl enable libvirtd

  3. Install Vagrant and other required packages, including the vagrant-libvirt plugin: 

    # yum install sclo-vagrant1 sclo-vagrant1-vagrant-libvirt \
  sclo-vagrant1-vagrant-libvirt-doc
    Note

    Before the packages are installed, you will be asked to confirm the importing of the Software Collections GPG key that was installed previously.

  4. Allow your regular user ID to start and stop Vagrant boxes. A PolicyKit rule will be added that allows users in the vagrant group to control VMs through libvirt. The necessary rule is included in the vagrant-libvirt package you just installed. Run the following command to add the rule on your system: 

    # cp /opt/rh/sclo-vagrant1/root/usr/share/vagrant/gems/doc/vagrant-libvirt-*/polkit/10-vagrant-libvirt.rules \
  /etc/polkit-1/rules.d

    The following is the contents of the newly created /etc/polkit-1/rules.d/10-vagrant-libvirt.rules rule for reference, or if you prefer to add it by hand:

    The /etc/polkit-1/rules.d/10-vagrant-libvirt.rules file

    /*
 * Allow users in vagrant group to manage libvirt without authentication.
 * Copy this file to /usr/share/polkit-1/rules.d/ to activate.
 */
polkit.addRule(function(action, subject) {
  if ((action.id == "org.libvirt.unix.manage"
    || action.id == "org.libvirt.unix.monitor")
    && subject.isInGroup("vagrant")) {
    return polkit.Result.YES;
  }
});

  5. Restart the libvirt and PolicyKit services for the changes to take effect: 

    # systemctl restart libvirtd
# systemctl restart polkit

  6. Check your user name, then become root to add your user name to the vagrant group. (Note that you need to log out and back in for the change to your group membership to take affect.) 

    $ echo $USER
joe
$ su -
Password:
# usermod -a -G vagrant joe

That completes the list of steps that need to be performed as root.

7.3. Setting Up Container Development Kit Software Components

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.

  1. Verify you are a member of the vagrant group (you may need to log in again to have the new group appear). 

    $ grep vagrant /etc/group
vagrant:x:978:joe
$ id
uid=1001(joe) gid=1001(joe) groups=1001(joe),978(vagrant)
context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023

  2. Enable the Vagrant Software Collection: 

    $ scl enable sclo-vagrant1 bash

  3. Verify that the system is set up to run Vagrant as a regular, non-root user: 

    $ vagrant global-status
id       name   provider state  directory
--------------------------------------------------------------------
There are no active Vagrant environments on this computer! Or,
you haven't destroyed and recreated Vagrant environments that were
started with an older version of Vagrant.

  4. Download the Container Development Kit 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 Container Tools

    • RHEL 7.3 Vagrant box for libvirt

      Note

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

  5. Unzip the downloaded ZIP file:

    Note

    The following steps assume you have saved the downloaded files in your home directory in ~/Downloads. If you used a different directory, adjust the paths accordingly. 

    ~/Downloads]$ unzip ~/Downloads/cdk-2.4.0.zip

    At this point, review the included README files to familiarize yourself with Red Hat Container Tools.

  6. Install the plugins contained in the unpacked cdk/plugins/ directory. Each plugin is in the form of a .gem file: 

    ~/Downloads]$ cd ~/cdk/plugins/
~/cdk/plugins]$ ls -1 *.gem
~/cdk/plugins]$ vagrant plugin install \
  ./vagrant-registration-*.gem \
  ./vagrant-service-manager-*.gem \
  ./vagrant-sshfs-*.gem

Note that the vagrant-sshfs plugin is dependent upon sftp-server.

  1. Verify that the vagrant-libvirt, vagrant-registration, vagrant-service-manager, and vagrant-sshfs plugins are properly installed by running the following command: 

    $ vagrant plugin list

  2. Add the Container Development Kit Vagrant box to Vagrant: 

    $ vagrant box add --name cdkv2 \
  ~/Downloads/rhel-cdk-kubernetes-7.*.x86_64.vagrant-libvirt.box
    Important

    The name you assign to the box using the --name parameter in this 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.

    To use a customized name for the box:

    1. Export the desired name to the BOX environment variable 

      $ export BOX=<box-name>

    2. Use the name in the vagrant box add command: 

      $ vagrant box add --name <box-name> rhel-cdk-kubernetes-7-*.x86_64.vagrant-libvirt.box

  3. Verify that the box is installed: 

    $ vagrant box list
cdkv2 (libvirt, 0)

    The box image file will be stored in your home directory under ~/.vagrant.d. You need adequate space there, approximately 3 GB.

7.4. Setting Up Container Development Kit for Use behind an HTTP Proxy

To run the Container Development Environment behind a proxy server, you need to export the proxy server information to the Container Development Environment and then run vagrant up (see Starting the Container Development Kit Vagrant Box on Red Hat Enterprise Linux).

Note

Currently, only HTTP and HTTPS proxy servers are supported.

7.4.1. Setting Proxy Environment Variables Manually

Run the following commands on the host system to export environment variables with information about the proxy server. This setting only remains in effect until you restart your session: 

$ export PROXY="<proxy-server>:<port>"
$ export PROXY_USER="<username>"
$ export PROXY_PASSWORD="<password>"

7.4.2. Using vagrant-service-manager to Set Proxy Environment Variables

To automatically export information about the proxy configuration to every Vagrant box that you start, use the vagrant-service-manager plugin. The following steps need to be completed:

  1. Include the following lines in your per-user Vagrantfile (~/.vagrant.d/Vagrantfile — note that you may need to create this file): 

    Vagrant.configure(2) do |config|
  config.servicemanager.proxy = '<proxy server>:<port>'
  config.servicemanager.proxy_user = '<proxy username>'
  config.servicemanager.proxy_password = '<proxy password>'
end

  2. Remove proxy-related configuration lines from the Container Development Kit Vagrantfile you intend to use.

    • To use the OpenShift Container Platform configuration, remove the following lines from the rhel-ose Vagrantfile (cdk/component/rhel/rhel-ose/Vagrantfile): 

      # explicitly enable and start OpenShift
config.vm.provision "shell", run: "always", inline: <<-SHELL
  PROXY=#{PROXY} PROXY_USER=#{PROXY_USER} PROXY_PASSWORD=#{PROXY_PASSWORD} IMAGE_TAG=#{IMAGE_TAG} /usr/bin/sccli openshift
SHELL

      And modify the following line to include the service your Vagrantfile needs to start (openshift): 

      # prevent the automatic start of openshift via service-manager by just enabling Docker
config.servicemanager.services = "docker, openshift"

    • To use the Kubernetes configuration, remove the following lines from the rhel-k8s-singlenode-setup Vagrantfile (cdk/components/rhel/misc/rhel-k8s-singlenode-setup/Vagrantfile): 

      # Explicitly enable and start kubernetes
config.vm.provision "shell", run: "always", inline: <<-SHELL
  PROXY=#{PROXY} PROXY_USER=#{PROXY_USER} PROXY_PASSWORD=#{PROXY_PASSWORD} /usr/bin/sccli kubernetes
  echo "kubernetes single node cluster setup successfully"
SHELL

      And modify the following line to include the service your Vagrantfile needs to start (kubernetes): 

      # prevent the automatic start of openshift via service-manager by just enabling Docker
config.servicemanager.services = "docker, kubernetes"
Note

To set the IP address used by the Vagrant box, set the PUBLIC_ADDRESS variable in the Vagrantfile for that box: 

# The private network IP of the VM. You will use this IP to connect to OpenShift.
# PUBLIC_ADDRESS="10.1.2.2"

PUBLIC_ADDRESS="x.x.x.x"

7.5. Starting the Container Development Kit Vagrant Box on Red Hat Enterprise Linux

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 Container Platform 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.

  1. Initialize the Container Development Kit Vagrant box:

    • Start Container Development Kit with OpenShift Container Platform as follows: 

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

      To use a different version of OpenShift Container Platform than the default (3.4.0.40), edit the IMAGE_TAG parameter in the rhel-ose Vagrantfile before running vagrant up. You can find the list of supported version tags at https://registry.access.redhat.com/v1/repositories/openshift3/ose/tags.

      For example: 

      IMAGE_TAG="v3.3.1.5"

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

      $ cd ~/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 ~/cdk/components/rhel/rhel-ose/
$ vagrant status

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