This document describes the process of setting up a VM running an OpenShift development environment inside VirtualBox.

Prerequisites

You need to have a virtualization application such as KVM, or VirtuaBox installed on your workstation and you will need at least 25GB of free disk space. The compressed download is about 1.3GB and when you unpack it the resulting image file is almost 4GB vmdk file or 20 GB uncompressed RAW disk file (Linux only).

1. Download VM

Download the VM from the OpenShift "mirrors" site:

$ wget https://mirror.openshift.com/pub/origin-server/release/4/images/openshift-origin.tgz

2. Unpack VM files

The download package is a compressed tar archive. Unpack it with tar xzf openshift-origin.tgz or your system’s archive utility. This can take a while, as the files being uncompressed are pretty large.

Once unpacked, you will find an "OpenShift Origin v4" directory with these contents:

$ ls -1t OpenShift\ Origin\ v4/
OpenShift Origin v4.vbox
origin-vm.vmdk
OpenShift Origin v4.vmx
OpenShift Origin v4.nvram
OpenShift Origin v4.vmsd
OpenShift Origin v4.vmxf

3. Configure mDNS

The VM image is configured to use mDNS to provide DNS name resolution so that your browser and RHC client can resolve the URL of the broker and applications running on the VM. mDNS services are built-in on MacOSX (bonjour) and Windows (zeroconf) system, but require a few addition steps on Fedora and other Linux-based systems.

  1. Install the mDNS resolver RPM:

    $ yum install -y nss-mdns
  2. Edit your /etc/nsswitch.conf file. Search for a list beginning with "hosts:" and add mdns4 to the end of the line. After the edit, it should look like:

    hosts:      files mdns4_minimal [NOTFOUND=return] dns myhostname mdns4

This will allow your browser and RHC client to properly resolve the hostname and application URLs.

4. Set up the Virtual Machine

The base VM image is distributed as a VMDK file and will run on a variety of virtualization technologies. Specific setup instructions are included below. Skip down to the one you intend to use.

  • libvirt/KVM - Kernel Virtual Machine (Linux)

  • VirtualBox - Process based virtualization (Linux, Windows, MacOS)

4.1. KVM

KVM or "Kernel Virtual Machine" (aka libvirt) is a Linux native virtualization mechanism. With KVM/libvirt installed on a Linux host you can run virtual machines for any Ix86 or x86_64 based operating system.

4.1.1. Installing KVM Tools

Start by installing the KVM/libvirt RPMs:

$ yum install -y virt-manager libvirt
This step may take a while depending on the speed of your internet connection.

4.1.2. Convert The Image

KVM requires a RAW disk image file. We can use qemu-img command to convert the VMDK image to RAW format.

Install the qemu-img RPM:

$ yum install -y qemu-img

Run qemu-img to convert the image file and then copy it into the libvirt directory.

$ qemu-img convert -O raw origin-vm.vmdk /var/lib/libvirt/images/origin-vm.dsk

4.1.3. Create New VM

Ensure that libvirt is running:

$ systemctl start libvirtd.service

Start virt-manager on the command line:

$ virt-manager

Once virt-manager starts, click on the "Create a new virtual machine" icon or right click on localhost and select New.

image

Enter "openshift_origin" as the name of the virtual machine, select "Import existing disk image" and click "Forward".

image

4.1.4. Select VM Disk Image

Select "Linux" as the "OS Type" and "Red Hat Enterprise Linux 6" as the version then click "Browse…" to select the disk image.

image

Select the "origin-vm.dsk" image and click "Choose Volume"

image

Once you are back to the setup screen, click "Forward".

4.1.5. Set VM Memory Size

Set the memory size to something reasonably large. 1GB should be a good start. Click the "Forward" button.

image

4.1.6. Set VM Memory Size

Select "Virtual Network default: NAT" network and click Finish to start the VM.

image

4.1.7. Starting the VM

When the VM has finished booting. It will go through some initialization and then present you with the URL a menu where you can start working with your VM.

image

4.2. VirtualBox

If Virtualbox is installed on your system, you should be able to click on the Openshift Origin v4.vbox file from a window manager to automatically register the VM and launch it.

If this doesn’t work, or if you would like to modify the VM configuration, read on.

4.2.1. Create New VM

You can start VirtualBox either by clicking on the desktop item in the startup menus or from the command line:

$ virtualbox &

When you start VirtualBox and you should see the welcome page. Click the New button in the upper left to begin the process of creating creating a new VM and importing the OpenShift virtual disk.

image

Fill in the name. It feels like VirtualBox knows that things called "OpenShift" will be Linux, but you should change the version to Fedora (64 bit) and click Next.

4.2.2. Set VM Memory Size

VirtualBox gives some of your computer’s memory to the virtual machine. You want it to be large enough so that the machine runs well, but not so large that it consumes all of your computer’s memory.

Set the memory size to something reasonably large. 1GB should be a good start. Click the Next button.

image

4.2.3. Select VM "Hard Drive" Image

Normally Virtualbox will create a new virtual hard drive for you. In this case you want to select the virtual disk image which contains the OpenShift Origin virtual machine.

Check the radio button labeled "Use an existing virtual hard drive file" and click the little folder icon with the green circumflex in the lower right corner.

image

VirtualBox will present a file selection dialog. Browse to find the "openshift-origin.vmdk" file and select it. Press the button labeled "Open".

image

Press the button labeled "Open".

image

When the disk has been selected click "Create". VirtualBox will create the stopped virtual machine and present the VM manager display.

image

4.2.4. Add Bridged Networking

By default VirtualBox uses Network Address Translation (NAT) to create a virtual network interface for your virtual machines. NAT will not let you connect back into your virtual machine. You need to add a second network adaptor configuration to use Bridged networking. Then your virtual machine will get an IP address from your DHCP server, and you will be able to use that address to browse or log in.

Highlight the OpenShift virtual machine (if it’s the only one, it will be already) and click the Settings icon (shaped like a gear) in the upper left corner. When the Settings window opens, select Network in the settings list.

image

Leave Adapter 1 as NAT and select the tab for Adapter 2.

  1. First, check the Enable Network Adapter box, which will unlock the other adapter settings.

  2. Next, set the Attached to: value to "Bridged Adapter"

  3. Finally, set the Name value to the network adapter that you want to bridge.

Each system may have different names for their physical network adaptors.

Press "OK" to finish changing the VM settings and return to the main window. Highlight the OpenShift Origin VM in the left hand column and click the "Start" button. VirtualBox will display the VM console as a black window and you can observe the boot process.

Virtualbox may show several informational dialog messages during startup about "Auto capture keyboard" and "mouse pointer integration". It is safe to click them away and to check the "don’t show me again" box when you do.

When the VM has finished booting. It will go through some initialization and then present you with the URL a menu where you can start working with your VM.

image

4.2.5. Odd Behavior on VirtualBox?

During testing we stumbled into a problem while running the OpenShift VM on VirtualBox. Specifically, VirtualBox chose a NAT subnet that our local network was already using. This led to a lot of confusion until we realized that requests to our VM were never reaching it; instead they were going out through the host’s network interface and getting lost in the digital wilderness. You may be encountering the same problem if:

  • You can’t connect from your host system to the VM via ssh root@<VM_IP_ADDR>

  • The VM’s welcome screen doesn’t list an IP address

  • App creations always time out in the console

So if you think this is affecting you, you can try an alternate network interface configuration in VirtualBox.

This configuration will prevent you from reaching the network beyond your host machine. Among other things, that means that you will not be able to create quickstart applications, even though they show up as options in the console.
  1. If the OpenShift Origin v4 VM is running, shut it down.

  2. In the main VirtualBox app, go to File ⇒ Preferences (or VirtualBox ⇒ Preferences on OS X). The Preferences window will appear.