Hooks

Node events

Most events are directly related to a node. The JSON input to the event script has a node property that contains the representation of the node in the same format the API produces for node details.

The JSON output of the event script can modify the node metadata:

{
  "node": {
    "metadata": {
      "update": {
        "example1": 8
      },
      "remove": [ "frob" ]
    }

Error handling

The hook script must exit with exit code 0 if it succeeds; any other exit code is considered a failure of the script.

Whether the failure of a script has any other effects depends on the event. A failed execution can still make updates to the hook and node objects by printing to stdout in the same way as a successful execution.

To report error details, the script produces a JSON object with an error property on its stdout in addition to exiting with a non-zero exit code. If the script exits with exit code 0, the error property is still recorded, but the event's severity isn't an error. The error property itself contains an object whose message property is a human-readable message; additional properties can be set. For example:

{
  "error": {
    "message": "connection refused by frobnicate.example.com",
    "port": 2345,
        ...
    ...
  }
}

Sample input

The input to the hook script is in JSON, containing a structure like this:

{
  "hook": {
    "name": "counter",
    "configuration": { "value": 0 }
  },
  "node": {
    "name": "node10",
    "hw_info": {
      "mac": [ "52-54-00-30-8e-45" ],
      ...
    },
    "dhcp_mac": "52-54-00-30-8e-45",
    "tags": ["compute", "anything", "any", "new"],
    "facts": {
      "memorysize_mb": "995.05",
      "facterversion": "2.0.1",
      "architecture": "x86_64",
      ...
    },
    "state": {
      "installed": false
      "physicalprocessorcount": "1",
    },
    "hostname": "client-l.watzmann.net",
    "root_password": "secret",
    "netmask_eth0": "255.255.255.0",
    "ipaddress_lo": "127.0.0.1",
    "last_checkin": "2014-05-21T03:45:47+02:00"
  },
  "policy": {
    "name": "client-l",
    "repo": "centos-6.7",
    "task": "ubuntu",
    "broker": "noop",
    "enabled": true,
    "hostname_pattern": "client-l.watzmann.net",
    "root_password": "secret",
    "tags": ["client-l"],
    "nodes": { "count": 0 }
  }
}

Sample hook

Here is an example of a basic hook called counter that counts the number of times Razor registers a node.

This example creates a corresponding directory for the hook type, counter.hook, inside the hooks directory. You can store the current count as a configuration entry with the key count. Thus the configuration.yaml file might look like this:

count:
  description: "The current value of the counter"
  default: 0

To make sure a script runs whenever a node is bound to a policy, create a file called node-bound-to-policy and place it in the counter.hook folder. Then write this script, which reads in the current configuration value, increments it, then returns some JSON to update the configuration on the hook object:

#! /bin/bash

json=$(< /dev/stdin)

name=$(jq '.hook.name' <<< $json)
value=$(( $(jq '.hook.config.count' <<< $json) + 1 ))

cat <<EOF
{
  "hook": {
    "configuration": {
      "update": {
        "count": $value
      }
    }
  },
  "node": {
    "metadata": {
      $name: $value
    }
  }
}
EOF

Note that this script uses jq, a bash JSON manipulation framework. This must be on the $PATH in order for execution to succeed.

Next, create the hook object, which stores the configuration:

razor create-hook --name counter --hook-type counter

Because the configuration is absent from this creation call, the default value of 0 in configuration.yaml is used. Alternatively, this could be set using --configuration count=0 or --c count=0.

The hook is now ready to use. You can query the existing hooks in a system via razor hooks. To query the current value of the hook's configuration, razor hooks counter shows count initially set to 0. When a node gets bound to a policy, the node-bound-to-policy script is triggered, yielding a new configuration value of 1.