Using OpenNebula hooks and Java RPC API for cloud process automation

OpenNebula is an open-source cloud computing framework for building private, public and hybrid cloud environments. Its goal is to provide an open, flexible and extensible management layer to automate and orchestrate the operations of existing (on-premises) or remote hardware infrastructure including networking, storage, virtualization, monitoring and user management. OpenNebula also support a mechanism called “hooks”; triggering of custom scripts, tied to the state change of a particular resource. Hooks can be a powerful feature, as they open a wide area of possibilities for system and process automation.

Hooks can be trigger by a state change in either Virtual Machine or Host. For Virtual Machine state changes, the hook script can be executed on the head node (OpenNebula cluster controller), or on the scheduled host directly. The hooks mechanism is available “out of the box”, so no additional installations or settings are required – apart from the hooks themselves, of course. To demonstrate the usage of hooks when extending the base OpenNebula system with our specific business and process flows, we included a simple example. The example is very easy to understand, yet not completely trivial and could also be used in a real-world scenario.

Let’s say we are the administrators of an OpenNebula cloud, which can be fully utilized by our client’s IT staff. The IT staff has full control over the virtual machines, but we’d still like to be informed when a VM is up & running, particularly about the VM’s owner and the host machine on which the VM is currently running. To achieve this, we will send an e-mail to a predefined address when any of the virtual machines enter the “running” state, along with the required VM’s runtime information.

Great! Now let’s get our hands dirty… The example system’s architecture is as follows:

• we will use the OpenNebula’s hooks mechanism to trigger a Ruby script when the state of a VM changes to RUNNING
• the Ruby script will pass the message containing the Virtual Machine’s ID to a server socket
• the Java socket server will, upon receiving a valid message, trigger the execution of our business logic
• the business logic will use OpenNebula’s Java RPC API to connect to the cloud, retrieve the VM’s runtime information and send an e-mail to a predefined address

1) We first have to define a new Virtual Machine hook for the “running” state. Open /etc/one/oned.conf or $ONE_LOCATION/etc/oned.conf (depending on your installation type). This is your Hook Manager’s configuration file. Add the following lines at the end of file:

VM_HOOK = [
  name = "demo_vmhook_running",
  on = "RUNNING",
  command = "demohook.rb",
  arguments = "VM RUNNING $VMID",
  remote = "no" ]

A little explanation won’t hurt:
- “name” is the name for the hook and can be anything, but it is useful to provide a descriptive enough name in case something goes wrong with the script or the hook itself – the name parameter will be displayed in the logs.
- “on” means the state this hook is bound to, in our case running. Other states include create, shutdown, stop, etc. For the complete list, please consult the documentation.
- “command” is the script file that gets executed when the hook is triggered. We use a Ruby script “demohook.rb” since Ruby is automatically installed with OpenNebula and quite easy to read.
- “arguments” is probably the most important part of hook’s definition, because we can access VM template variables with $ sign. Hence, $VMID means the ID of the Virtual Machine that just entered the RUNNING state.
- “remote” is currently set to “no”, because we want the “demohook.rb” script to be executed on the head-node, where our Java program is running. By setting this to “yes”, the script is executed remotely (on the host where the VM was scheduled to run), which can also be quite a powerful feature of OpenNebula.

2) Create the Ruby script demohook.rb and place it in /usr/share/one/hooks or $ONE_LOCATION/share/hooks, depending on your installation type:

#!/usr/bin/env ruby
require 'socket'

begin
  if(!ARGV.at(2))
    puts("3 arguments required")
  else
    sck = TCPSocket.new("127.0.0.1", 3344)
    if(sck)
      sck.write(ARGV[0] + "_" + ARGV[1] + "_" + ARGV[2])
      sck.close
    end
  end
rescue Errno::ECONNREFUSED
  p 'TCP socket connection refused on port 3344 - is Java socket server running?'
end

The script is also available in the source zip file. You can change the port number (3344), but please make sure you also change the port in Java program accordingly (file HooksListener.java).

3) Restart OpenNebula by issuing the following command:
$ sudo service opennebula restart

OK, we have just installed the OpenNebula hook along with the script, which will just pass the arguments to a server socket on port 3344. Now we need the socket listener to trigger the execution of our business logic (get VM’s runtime information and send it via e-mail to the system administrator). We will use Java programming language to utilize the Java RPC API and take full control of the rest of the process. This approach allows us to keep the Ruby script as simple as possible and free of any specific business logic, as Java code is usually easier to maintain and extend. We could, of course, limit ourselves to Ruby only and put everything in “demohook.rb” script. It doesn’t even have to be Ruby, it could also be Python, plain old shell script or maybe even PHP. But to demonstrate this example better, the socket connection between Ruby and Java seemed like a good idea. OK, let’s take care of the last part…

4) Download and extract this zip file on your OpenNebula head node, preferably inside your home directory. We recommend you put all the files in opennebula_hooks_demo subdirectory, apart from the “demohooks.rb” script, which you should put as per #2 above (if not created already). Now open the build.xml file and change the “basedir” property (line #1) to whatever your home folder is:
<project name="OpenNebulaHooksDemo" basedir="/YOUR_HOME_FOLDER/opennebula_hooks_demo" default="main">

5) We’re almost done, we just need to change of couple of settings:
Open the file /YOUR_HOME_FOLDER/opennebula_hooks_demo/src/si/cloud/opennebula/MailSender.java and specify your e-mail server, username, password and other information required by javax.mail transport:
private static final String MAIL_HOST = "smtp.gmail.com";
private static final int MAIL_PORT = 465;
private static final String MAIL_USERNAME = "my.email@gmail.com";
private static final String MAIL_PASSWORD = "mypassword";
private static final String MAIL_FROM = "from@gmail.com";
private static final String MAIL_TO = "to@gmail.com";

To retrieve VM’s runtime information from OpenNebula, we use Java RPC API. Full API documentation can be found here, but for this example to work, you just need to double-check the basic connection settings. Open the file /YOUR_HOME_FOLDER/opennebula_hooks_demo/src/si/cloud/opennebula/OpenNebula.java and change the settings accordingly.
private static final String ONE_RPC_HOST = "localhost";
private static final String ONE_RPC_PORT = "2633";
private static final String ONE_ADMIN_USERNAME = "oneadmin";
private static final String ONE_ADMIN_PASSWORD = "oneadmin";

6) Make sure Java 6 (or above) and Apache Ant are installed on your head node. You can run the example Java program by issuing the ant command in the project’s base directory, e.g. /YOUR_HOME_FOLDER/opennebula_hooks_demo (which should also be the directory containing Ant’s build.xml file).

If you encounter any problems setting up the system, please feel free to send me an e-mail or post a comment below.

API, automation, Cloud Computing (CC), opennebula, Ruby