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).
Download the VM from the OpenShift "mirrors" site:
$ wget https://mirror.openshift.com/pub/origin-server/release/4/images/openshift-origin.tgz
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
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.
Install the mDNS resolver RPM:
$ yum install -y nss-mdns
/etc/nsswitch.conffile. 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.
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.
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.
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.|
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
Ensure that libvirt is running:
$ systemctl start libvirtd.service
Start virt-manager on the command line:
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".
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".
Set the memory size to something reasonably large. 1GB should be a good start. Click the "Forward" button.
Select "Virtual Network default: NAT" network and click Finish to start the VM.
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.
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.
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.
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.
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.
First, check the Enable Network Adapter box, which will unlock the other adapter settings.
Next, set the Attached to: value to "Bridged Adapter"
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.
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
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.|
If the OpenShift Origin v4 VM is running, shut it down.
In the main VirtualBox app, go to File ⇒ Preferences (or VirtualBox ⇒ Preferences on OS X). The Preferences window will appear.