During the last months, at OpenNebula Systems we’ve been working on a complete redesign of the hooks subsystem. In this post we will go through all the new features.

API Hooks

One of the most powerful features that we have added is API Hooks, which allow the cloud administrator to define a hook for any OpenNebula API call. This provides huge flexibility for managing different OpenNebula events.

The introduction of API Hooks has now slightly changed the way legacy hooks work (so please check compatibility guide before upgrading to OpenNebula 5.10), and some legacy hooks need to be adapted to use the new API hooks. For example, if you want to define a hook for being triggered when a new virtual network is created, you now have to define a hook for the “one.vn.allocate” API call.

Hook Management

In previous versions of OpenNebula, hooks were managed via oned.conf. Whenever a cloud administrator needed to create, update or delete a hook, the oned.conf file had to be updated and the OpenNebula service restarted.

With the new hook subsystem, hooks can be managed by using the CLI or the API. This provides the cloud administrator more flexibility for managing them. Below there are some examples showing how easy is to manage hooks via CLI:

#Create a hook to trigger an alarm on host error
$ cat > hook.tmpl << EOF 
NAME = hook
TYPE = state
COMMAND = trigger_alarm.rb
STATE = ERROR
RESOURCE = HOST
EOF

$ onehook create /tmp/hook.tmpl 
ID: 0

#Check the hook information
$ onehook show 0
HOOK 0 INFORMATION                                                              
ID          : 0                   
NAME        : hook                
TYPE        : state               
LOCK        : None                

HOOK TEMPLATE                                                                   
COMMAND="trigger_alarm.rb"
REMOTE="NO"
RESOURCE="HOST"
STATE="ERROR"

#Delete the hook
$ onehook delete 0

$ onehook list
  ID NAME                TYPE

Hook Execution Result

The new hook system also provides a way to check whether a hook execution was successful or not, as well as a way to retry a hook execution, if needed.

When a hook is defined, we can check a quick summary of their execution records by showing its detailed information. Let’s create a hook and review what it looks like:

$ cat > hook.tmpl << EOF
NAME = hook
TYPE = api
COMMAND = "/$(which cat)"
ARGUMENTS = "one.zone.info call performed"
ARGUMENTS_STDIN = yes
CALL = "one.zone.info"
EOF

$ onehook create /tmp/hook.tmpl
ID: 1

$ onezone show 0
ZONE 0 INFORMATION                                                              
ID                : 0                   
NAME              : OpenNebula          


ZONE TEMPLATE  
ENDPOINT="http://localhost:2633/RPC2"

$ onehook show 1
HOOK 1 INFORMATION                                                              
ID                : 1                   
NAME              : hook                
TYPE              : api                 
LOCK              : None                

HOOK TEMPLATE                                                                   
ARGUMENTS="one.zone.info call performed"
ARGUMENTS_STDIN="yes"
CALL="one.zone.info"
COMMAND="//usr/bin/cat"
REMOTE="NO"

EXECUTION LOG
   ID     TIMESTAMP    RC EXECUTION
    0     09/25 15:25   0 SUCCESS

You can see that there is one SUCCESS execution. But that’s not all, OpenNebula saves much more information about the hook executions, like STDOUT, STDERR… you can see all this information by using the -e option of onehook show command:

$ onehook show 1 -e 0
HOOK 1 INFORMATION                                                              
ID                : 1                   
NAME              : hook                
TYPE              : api                 
LOCK              : None                

HOOK EXECUTION RECORD                                                           
EXECUTION ID      : 0                   
TIMESTAMP         : 09/25 15:25:32      
COMMAND           : //usr/bin/cat       
ARGUMENTS         : one.zone.info call performed 
EXIT CODE         : 0                   

EXECUTION STDOUT                                                                
one.zone.info call performed 

EXECUTION STDERR  

In this example the hook STDOUT includes the text we sent as an argument to the cat command. Note that we pass the arguments via STDIN by using ARGUMENTS_STDIN="yes" in the hook template. 

Now that we have the records of each hook execution, we can retry exactly the same execution by running the command onehook retry:

$ onehook retry 1 0

$ onehook show 1
HOOK 1 INFORMATION                                                              
ID                : 1                   
NAME              : hook                
TYPE              : api                 
LOCK              : None                

HOOK TEMPLATE                                                                   
ARGUMENTS="one.zone.info call performed"
ARGUMENTS_STDIN="yes"
CALL="one.zone.info"
COMMAND="//usr/bin/cat"
REMOTE="NO"

EXECUTION LOG
   ID       TIMESTAMP    RC EXECUTION
    0     09/25 15:25     0 SUCCESS
    1     09/25 15:33     0 SUCCESS

We now see two executions, the one with ID 1 being the retry execution.

Regarding to hook executions log, there is another tool which allows the cloud administrator to quickly check if there is some hook execution to worry about. The onehook log command shows all the hook executions and allows the cloud administrator to filter by time period, hook id or hook execution result (success or error). Let’s see some examples:

$ onehook log --since "2019/09/25"            
 HOOK    ID    TIMESTAMP    RC EXECUTION
    1     1     09/25 15:33     0    SUCCESS
    1     0     09/25 15:25     0    SUCCESS

$ onehook log --since "2019/09/25" --error

$ onehook log --until "2019/09/25" --success

While this is just a quick overview, you can see that the updates to come in v.5.10 for the Hooks Subsystems are here to make more information available and to bring additional overall value to their usage. If you have any feedback to share, we’d love to hear what you think.