Skip to content
Hands-on IT IT Drills

Day 11: OneGate and Hooks

Goal: Have VMs report their state to OpenNebula and react to events in OpenNebula with your own scripts. · Duration: approx. 60 min · Prerequisite: Day 10

Briefing

Two directions, two tools:

Tool Direction Example
OneGate VM → OpenNebula “I am ready”, “I have 42 notes”
Hooks OpenNebula → script on the front-end “VM is running” → log entry, ticket, chat
  • OneGate is a small REST service (port 5030). A VM may use it if its context contains TOKEN = "YES". It then gets a token that is valid only for itself. The onegate command inside the VM uses it.
  • REPORT_READY = "YES" makes one-context report READY=YES after start. OneFlow waits for this with ready_status_gate (Day 9).
  • Hooks are run by the Hook Execution Manager (opennebula-hem). A state hook reacts to state changes, an API hook to calls of the XML-RPC API.
 VM ── onegate vm update ──► OneGate :5030 ──► oned: USER_TEMPLATE der VM
 oned ── VM wird RUNNING ──► HEM ──► /usr/local/bin/vm-laeuft.sh <Template als Base64>

Drill 1: Token for the template

The alpine template from Day 4 gets two lines in its context:

mkdir -p ~/one-lab/tag11
cd ~/one-lab/tag11
sed 's/  NETWORK = "YES",/  NETWORK = "YES",\n  TOKEN = "YES",\n  REPORT_READY = "YES",/' \
  ../tag04/alpine.tpl > alpine.tpl
grep -A3 '^CONTEXT' alpine.tpl
onetemplate update alpine alpine.tpl

Expected:

CONTEXT = [
  NETWORK = "YES",
  TOKEN = "YES",
  REPORT_READY = "YES",

onetemplate update replaces the content; the permissions from Day 8 remain.

onetemplate instantiate alpine --name gate --user-inputs GRUSS=g

After a minute:

onevm show gate | grep -E 'READY|ONEGATE'

Expected:

READY="YES"
  ONEGATE_ENDPOINT="http://169.254.16.9:5030",
  REPORT_READY="YES",

The VM reported READY="YES" itself. The address 169.254.16.9 is a link-local address that OpenNebula forwards to OneGate on every host. That way, even VMs in networks without a gateway reach the service.

Save your progress? Sign up for free

Drill 2: Report your own values

IP=$(onevm show gate | grep -o 'ETH0_IP="[0-9.]*' | cut -d'"' -f2)
ssh $IP 'onegate vm update --data "NOTIZEN=1
STATUS=bereit"'
onevm show gate | sed -n '/USER TEMPLATE/,$p' | grep -E 'NOTIZEN|STATUS'

Expected:

NOTIZEN="1"
STATUS="bereit"

The values are now in the VM’s USER_TEMPLATE, visible in the CLI, Sunstone, and the API. This way, an appliance can expose its version, its URL, or an error without anyone having to log in.

The VM may also read:

ssh $IP onegate vm show

Expected:

VM 35
NAME                : gate

It may not do more. The token is valid only for this one VM and, if it belongs to a OneFlow service, for its siblings in the service (onegate service show).

Save your progress? Sign up for free

Drill 3: A hook

Every time a VM is running, an entry should go to the system log. The hook receives the entire VM template as Base64 XML. A small script extracts the name:

cat > vm-laeuft.sh <<'EOF'
#!/bin/sh
# Hook: $1 is the VM's template as Base64 XML
NAME=$(echo "$1" | base64 -d | grep -o "<NAME>[^<]*" | head -1 | cut -d">" -f2)
logger -t opennebula-hook "VM $NAME läuft"
EOF
sudo install -m 755 vm-laeuft.sh /usr/local/bin/vm-laeuft.sh
cat > laeuft.hook <<'EOF'
NAME = "vm-laeuft"
TYPE = "state"
RESOURCE = "VM"
ON = "RUNNING"
COMMAND = "/usr/local/bin/vm-laeuft.sh"
ARGUMENTS = "$TEMPLATE"
EOF
onehook create laeuft.hook

Expected:

ID: 2
  • ON = "RUNNING" is a shorthand for the change to ACTIVE/RUNNING. Others are PROLOG, SHUTDOWN, STOP, DONE, UNKNOWN, or CUSTOM with your own STATE and LCM_STATE.
  • The script runs on the front-end as the user oneadmin. That is why it lives in /usr/local/bin, where oneadmin may execute it.

Tried it: Without ON, onehook create fails with Unkown state condition (sic). And in ARGUMENTS, OpenNebula only replaces $TEMPLATE and a few other placeholders; an $ID stays empty. That is why the script reads the name from the template.

A VM to try it out:

onetemplate instantiate alpine --name hooktest --user-inputs GRUSS=h

After a minute:

onehook show vm-laeuft | sed -n '/EXECUTION LOG/,$p'
sudo journalctl -t opennebula-hook --since "-5min" --no-pager | tail -1

Expected (times will differ):

EXECUTION LOG
   ID       TIMESTAMP    RC EXECUTION
    0     11/12 20:25     0 SUCCESS
Nov 12 20:25:07 one opennebula-hook[1290086]: VM hooktest läuft

onehook show vm-laeuft -e 0 shows the complete execution with command, arguments, and output. That is the first place to look when a hook ends with an RC other than 0.

Save your progress? Sign up for free

Checkpoint

onehook list

Expected: vm-laeuft of type state.

onevm show gate | grep READY=

Expected: READY="YES".

Challenge

A second hook vm-weg should write to the log when a VM is deleted. Delete hooktest and check the log.

Solution

sed -e 's/vm-laeuft"/vm-weg"/' -e 's/"RUNNING"/"DONE"/' -e 's|vm-laeuft.sh|vm-weg.sh|' \
  laeuft.hook > weg.hook
sed 's/läuft/ist gelöscht/' vm-laeuft.sh > vm-weg.sh
sudo install -m 755 vm-weg.sh /usr/local/bin/vm-weg.sh
onehook create weg.hook
onevm terminate --hard hooktest

A few seconds later:

sudo journalctl -t opennebula-hook --since "-1min" --no-pager | tail -1

Expected:

Nov 12 20:25:57 one opennebula-hook[1291354]: VM hooktest ist gelöscht

DONE is the last state of a VM. After that, it only exists in the history.

Clean up:

onevm terminate --hard gate

The hooks stay; they do no harm.

Save your progress? Sign up for free

Enterprise Note

  • Hooks for integrations: Typical hooks register new VMs in a CMDB, add them to DNS, or open a ticket when a host reports ERROR. For hosts, there is a ready-made hook template that restarts the VMs on other hosts when a host fails.
  • Monitoring from the VM: OneGate is no replacement for Prometheus, but it is handy for values OpenNebula itself needs, for example for OneFlow’s elasticity rules.
  • Token protection: The OneGate token lives inside the VM. Whoever is root in the VM can describe the VM via OneGate, but nothing more. If you do not need OneGate, leave out TOKEN.