Skip to content
This repository has been archived by the owner. It is now read-only.
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
370 lines (250 sloc) 13.8 KB

OpenShift Origin Virtual Machine Deployment Guide

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


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

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


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


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.


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


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.


4.1.6. Set VM Memory Size

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


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.


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.


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.


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.


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


Press the button labeled "Open".


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


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.


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.


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.


  3. In the Preferences window, click on the Network tab, and once on the Network tab, choose the Host-only Networks subtab.


  4. If no host-only networks are listed, create one by pressing the "+" icon. A new host-only network will appear with a name like "vboxnet0".


  5. Now press OK to close the Preferences window. Then, in the VirtualBox Manager main window, select the OpenShift Origin v4 VM and press the Settings button. The VM settings will appear.


  6. Click on the Network tab. The Adapter 1 tab should be selected. From the Attached to: pulldown, select Host-only Adapter. Below that pulldown, the Name pulldown should automatically populate with the name of the Host-only adapter that you created.


  7. Now change to the Adapter 2 tab, and if the Enable Network Adapter checkbox is checked for Adapter 2, uncheck it. Finally, press OK to close the machine Settings window.


Now you should be able to launch the VM and work with it as described.

4.3. VMWare

Provided with the VM is a file called OpenShift Origin 4.vmx. If VMWare is installed on your system, you should be able to double-click this vbox file from within a file manager and VMWare will automatically register the VM for you.

5. Accessing the Virtual Machine

When the VM is running it is accessible from the host machine either using the OpenShift console via a web browser or on a command line interface using SSH. The web interface is useful for easily managing applications while the CLI allows the user to write and test applications and components. The web browser will also be used to verify the test applications during development.

5.1. User Accounts

When you boot the VM, the system automatically logs in the root user. The startup screen that is displayed includes the root login information:

  • Username: root

  • Password: changeme

The VM also includes one registered OpenShift user:

  • Username: demo

  • Password: changeme

This OpenShift user account can be used to log into the web console and can also be used to create and manage apps via the rhc command line utility.

To create a new OpenShift user account, run the following command as the root user on the VM:

$ htpasswd /etc/openshift/htpasswd <username>

You will be prompted to set a password for the new user.

5.2. Using a browser to view the OpenShift Console

When the VM is running you can use the OpenShift Console to create and manage applications in the VM. Enter the URL from the CLI boot console into your browser. Enter the username and password when prompted.


5.3. Using SSH to log into the VM

Most of the OpenShift workflow for application development is done from the command line. The OpenShift VM has an account created and populated with the tools needed to create, manage and develop apps for demonstration purposes.

The user reaches the command line on the VM using SSH from the host.

$ ssh openshift@broker.openshift.local
The authenticity of host 'broker.openshift.local (' can't be established.
RSA key fingerprint is 4f:bd:75:14:c2:27:83:2d:9b:e0:a6:1a:00:d4:7b:f1.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'broker.openshift.local,' (RSA) to the list of known hosts.
openshift@broker.openshift.local's password:
[openshift@broker ~]$ pwd
[openshift@broker ~]$

At this point the user has access to the rhc command line tools for managing OpenShift.

6. Summary

The steps above allow a user to download and run a self-contained OpenShift service for development or demonstration purposes. The service runs in a VirtualBox virtual machine and is accessible to the user on the host machine using the VirtualBox graphical console, by SSH or with a local web browser to the OpenShift console and to any applications that are created within the OpenShift service.

You can’t perform that action at this time.