Red Hat Training

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

Chapter 4. Using Vagrant Container Development Kit Plugins

Container Development Kit comes with several plugins that provide added features you can use with your Vagrant boxes. This chapter contains descriptions of those plugins and ways to use them.

4.1. Using the vagrant-service-manager Plugin

On the host machine, you can use the vagrant-service-manager plugin to obtain information about the Docker, OpenShift, and Kubernetes services running in the virtual machine. It displays environment variables that need to be set on the host system (your development workstation) to enable host-based tools (such as the Eclipse IDE, the docker command, or OpenShift’s oc command) to interact with the Docker daemon from the virtual machine.

The vagrant-service-manager plugin automatically recognizes the host operationg system and outputs information based on the platform.

4.1.1. Setting the Host Environment on Linux and macOS

Run the following command from the directory in which the Vagrant box was initialized (in this example, the rhel-ose Vagrantfile was used to provision the Container Development Kit Vagrant box):

~/cdk/components/rhel/rhel-ose]$ vagrant service-manager env
Configured services:
docker - running
openshift - running
kubernetes - stopped

docker env:
# Set the following environment variables to enable access to the
# docker daemon running inside of the vagrant virtual machine:
export DOCKER_HOST=tcp://10.1.2.2:2376
export DOCKER_CERT_PATH=/home/john/down/cdk/components/rhel/rhel-ose/.vagrant/machines/default/libvirt/docker
export DOCKER_TLS_VERIFY=1
export DOCKER_API_VERSION=1.22
# run following command to configure your shell:
# eval "$(vagrant service-manager env docker)"

openshift env:
You can access the OpenShift console on: https://10.1.2.2:8443/console
To use OpenShift CLI, run: oc login https://10.1.2.2:8443

Run the following command to set the required environment variables, so that the docker client on the host system can be used to interact with the Docker service running inside the Container Development Kit virtual machine:

~]$ eval "$(vagrant service-manager env docker)"

4.1.2. Setting Up the Host Environment on Microsoft Windows

Run the following command from the directory in which the Vagrant box was initialized (in this example, the rhel-ose Vagrantfile was used to provision the Container Development Kit Vagrant box).

~/cdk/components/rhel/rhel-ose]$ vagrant service-manager env docker
# Set the following environment variables to enable access to the
# docker daemon running inside of the vagrant virtual machine:
export DOCKER_HOST=tcp://10.1.2.5:2376
export DOCKER_CERT_PATH='C:\cygwin64\home\cdk\cdk\components\rhel\rhel-ose\.vagrant\machines\default\virtualbox\docker\'
export DOCKER_TLS_VERIFY=1
export DOCKER_API_VERSION=1.22
# run following command to configure your shell:
# eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager env docker | tr -d '\r')"

openshift env:
You can access the OpenShift console on: https://10.1.2.2:8443/console
To use OpenShift CLI, run: oc login https://10.1.2.2:8443

To set the required environment variables, so that the docker.exe client on the host system can be used to interact with the Docker service running inside the Container Development Kit virtual machine, you need to run the following commands (note that you need to use the Cygwin Bash environment for the commands to work properly):

~]$ export VAGRANT_DETECTED_OS=cygwin

~]$ eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager env docker | tr -d '\r')"

4.2. Using the vagrant-registration Plugin

With the vagrant-registration plugin, you can manage Red Hat subscriptions for your Red Hat Enterprise Linux virtual machines through Vagrant.

4.2.1. Understanding Red Hat Enterprise Linux Subscription for Container Development Kit

Registering your Red Hat Enterprise Linux system is highly recommended. Until you register, you cannot use the official Red Hat repositories to:

  • Upgrade the software in your Red Hat Enterprise Linux virtual machine.
  • Add more software packages to your Red Hat Enterprise Linux virtual machine.
  • Add software packages to the Red Hat Enterprise Linux containers you build or run on that virtual machine.

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 Container Development Kit virtual machine with Red Hat is automated using the vagrant-registration plugin. By default, when a Vagrant box is started, you are prompted to enter your username and password for the Red Hat Customer Portal. When the registration plugin is properly configured, the Vagrant box is automatically attached to an available subscription.

When a Red Hat Enterprise Linux VM is registered in Container Development Kit, 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 Container Development Kit entitlement expires. Once the time limit is up, that container loses access to the Red Hat software repositories (CDN).

You can register your Container Development Kit system with a valid Red Hat Enterprise Linux Developer Subscription. Joining the Red Hat Developers program also provides a path to getting registration credentials. Once you register a Container Development Kit 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.

4.2.2. Releasing a Subscription

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

  • When you stop the Vagrant box, using either vagrant halt or vagrant destroy, the plugin automatically releases the Red Hat subscription.
  • If you stop the box by some other means, such as a reboot of the host system, you may need to manually remove the subscription in order to use it on another box. Use subscription management at Red Hat Customer Portal Subscriptions to find and delete the virtual system that is no longer being used.
  • If you do not want to unregister a system when it is halted, you can set config.registration.unregister_on_halt = false in the selected Vagrantfile. In that case, the subscription will still be intact the next time you run vagrant up on that Vagrantfile.

4.2.3. Automating the Registration Process (Saving Your Credentials)

It is recommended that you store your Red Hat credentials, so that you do not have to answer the prompts every time you bring up a Vagrant box. This is mandatory for complex Vagrantfiles that bring up multiple virtual machines from a single Vagrantfile.

To store your credentials, the following lines should be added to the per-user Vagrantfile. The path to that file is different for the different platforms:

  • Microsoft Windows: %USERPROFILE%\.vagrant.d\Vagrantfile
  • Red Hat Enterprise Linux and macOS: ~/.vagrant.d/Vagrantfile

The configuration will be available to all boxes started under that user ID. The per-user Vagrantfile is not created automatically.

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

To avoid storing your Red Hat credential details in the file system, you can use the following configuration to retrieve them from environment variables. Remember to store your username in the $SUB_USERNAME environment variable (SUB_USERNAME for Microsoft Windows) and your password in the $SUB_PASSWORD environment variable (SUB_PASSWORD for Microsoft Windows) before starting Vagrant.

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

These settings may also be used in a specific Vagrantfile that will override the settings in the per-user ~/.vagrant.d/Vagrantfile. In an existing Vagrantfile, there will already be a block that begins with Vagrant.configure('2') do |config|, so just add the two config.registration lines (see above) in the existing block.

For more information, see the vagrant-registration-README.md file in the ~/cdk/plugins directory of the Red Hat Container Tools ZIP file.

4.2.4. Additional Resources