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
-
Edit your
/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.
-
libvirt/KVM - Kernel Virtual Machine (Linux)
-
VirtualBox - Process based virtualization (Linux, Windows, MacOS)
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
|
Note
|
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:
$ 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".
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.
|
Note
|
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
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.
|
Warning
|
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.
-
In the Preferences window, click on the Network tab, and once on the Network tab, choose the Host-only Networks subtab.
-
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".
-
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.
-
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.
-
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.
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.
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.
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.
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 (10.18.17.93)' 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,10.18.17.93' (RSA) to the list of known hosts. openshift@broker.openshift.local's password: [openshift@broker ~]$ pwd /home/openshift [openshift@broker ~]$
At this point the user has access to the rhc command line tools for
managing OpenShift.
See the OpenShift User’s Guide
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.