foreman_hooks 0.2.0 → 0.3.0

data/README.md

@@ -1,11 +1,12 @@
 # foreman_hooks
 
 Allows you to trigger scripts and commands on the Foreman server at any point
-in an object's lifecycle in Foreman.  This lets you run a script when a host
+in an object's lifecycle in Foreman.  This lets you run scripts when a host
 is created, or finishes provisioning etc.
 
-It observes every object in Foreman and exposes the Rails callbacks by running
-scripts within its hooks directory.
+It enables extension of Foreman's host orchestration so additional tasks can
+be executed, and can register hooks into standard Rails callbacks for any
+Foreman object, all with shell scripts.
 
 # Installation:
 
@@ -29,7 +30,8 @@ To upgrade to newest version of the plugin:
 
 Hooks are stored in `/usr/share/foreman/config/hooks` (`~foreman/config/hooks`)
 with a subdirectory for the object, then a subdirectory for the event name.
-Each file within the directory is executed in alphabetical order.
+
+    ~foreman/config/hooks/$OBJECT/$EVENT/$HOOK_SCRIPT
 
 Examples:
 
@@ -37,17 +39,15 @@ Examples:
     ~foreman/config/hooks/host/destroy/15_cleanup_database.sh
     ~foreman/config/hooks/smart_proxy/after_create/01_email_operations.sh
 
-Note that in Foreman 1.1, hosts are just named `Host` so hooks go in a `host/`
-directory, while in Foreman 1.2 they're `Host::Base` and `Host::Managed`, so
-the hook directory becomes `host/base/` and `host/managed/` respectively.
+In Foreman 1.1, all hosts are `host` but in Foreman 1.2, managed hosts will
+become `host/managed` instead.
 
 ## Objects / Models
 
 Every object (or model in Rails terms) in Foreman can have hooks.  Check
 `~foreman/app/models` for the full list, but these are the interesting ones:
 
-* `host` (Foreman 1.1), `host/managed` (Foreman 1.2)
-* `host/discovered` (Foreman 1.2)
+* `host` (or `host/managed` in Foreman 1.2)
 * `report`
 
 ## Orchestration events
@@ -65,21 +65,22 @@ To add hooks to these, use these event names:
 
 ## Rails events
 
-These are the most interesting events that Rails provides and this plugin
-exposes:
+For hooks on anything apart from hosts (which support orchestration, as above)
+then the standard Rails events will be needed.  These are the most interesting
+events provided:
 
-* `after_create`
-* `after_destroy`
+* `after_create`, `before_create`
+* `after_destroy`, `before_destroy`
 
 Every event has a "before" and "after" hook.  For the full list, see the
 Constants section at the bottom of the
 [ActiveRecord::Callbacks](http://api.rubyonrails.org/classes/ActiveRecord/Callbacks.html)
 documentation.
 
-The host object has two special callbacks in Foreman 1.1 that you can use:
+The host object has two additional callbacks that you can use:
 
-* `host/after_build` triggers when a host is put into Build mode(??)
-* `host/before_provision` triggers... (??)
+* `host/after_build` triggers when a host is put into build mode
+* `host/before_provision` triggers when a host completes the OS install
 
 ## Execution of hooks
 
@@ -89,16 +90,33 @@ Hooks are executed in the context of the Foreman server, so usually under the
 The first argument is always the event name, enabling scripts to be symlinked
 into multiple event directories.  The second argument is the string
 representation of the object that was hooked, e.g. the hostname for a host.
-No other data about the object is currently made available.
+
+    ~foreman/config/hooks/host/create/50_register_system.sh create foo.example.com
+
+A JSON representation of the hook object will be passed in on stdin.  A utility
+to read this with jgrep is provided in `examples/hook_functions.sh` and
+sourcing this utility script will be enough for most users.  Otherwise, you
+may want to ensure stdin is closed.
+
+    echo '{"host"=>{"name"=>"foo.example.com"}}' \
+      | ~foreman/config/hooks/host/create/50_register_system.sh \
+           create foo.example.com
 
 Every hook within the event directory is executed in alphabetical order.  For
 orchestration hooks, an integer prefix in the hook filename will be used as
 the priority value, so influences where it's done in relation to DNS, DHCP, VM
 creation and other tasks.
 
-If a hook fails (non-zero return code), the event is logged.  
+## Hook failures and rollback
+
+If a hook fails (non-zero return code), the event is logged.  For Rails events,
+execution of other hooks will continue.
+
 For orchestration events, a failure will halt the action and rollback will
-occur.  For Rails events, execution of other hooks will continue.
+occur.  If another orchestration action fails, the hook might be called again
+to rollback its action - in this case the first argument will change as
+appropriate, so must be obeyed by the script (e.g. a "create" hook will be
+called with "destroy" if it has to be rolled back later).
 
 # Copyright
 

data/examples/hook_functions.sh

@@ -0,0 +1,28 @@
+# Utilities for hook scripts, used with foreman_hooks
+#
+# Source this at the start of any bash hook script:
+#
+#   . hook_functions.sh
+#
+# It reads in a JSON representation of the object and then provides a
+# hook_data wrapper around jgrep to read fields from it, e.g.
+#
+#   hostname=$(hook_data host.name)
+#   comment=$(hook_data host.comment)
+
+# update, create, before_destroy etc.
+HOOK_EVENT=$1
+# to_s representation of the object, e.g. host's fqdn
+HOOK_OBJECT=$2
+
+HOOK_OBJECT_FILE=$(mktemp foreman_hooks.XXXXXXXXXX)
+trap "rm -f $HOOK_OBJECT_FILE" EXIT
+cat > $HOOK_OBJECT_FILE
+
+hook_data() {
+  if [ $# -eq 1 ]; then
+    jgrep -s "$1" < $HOOK_OBJECT_FILE
+  else
+    jgrep "$*" < $HOOK_OBJECT_FILE
+  fi
+}

data/examples/log.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+. $(dirname $0)/hook_functions.sh
+
+# event name (create, before_destroy etc.)
+# orchestration hooks must obey this to support rollbacks (create/update/destroy)
+event=${HOOK_EVENT}
+
+# to_s representation of the object, e.g. host's fqdn
+object=${HOOK_OBJECT}
+
+# Example of using hook_data to query the JSON representation of the object
+# passed by foreman_hooks.  `cat $HOOK_OBJECT_FILE` to see the contents.
+hostname=$(hook_data host.name)
+
+echo "$(date): received ${event} on ${object}" >> /tmp/hook.log
+
+# exit code is important on orchestration tasks
+exit 0

data/foreman_hooks.gemspec

@@ -1,8 +1,8 @@
 Gem::Specification.new do |s|
   s.name = "foreman_hooks"
 
-  s.version = "0.2.0"
-  s.date = "2013-03-24"
+  s.version = "0.3.0"
+  s.date = "2013-04-06"
 
   s.summary = "Run custom hook scripts on Foreman events"
   s.description = "Plugin engine for Foreman that enables running custom hook scripts on Foreman events"

data/lib/foreman_hooks/engine.rb

@@ -13,10 +13,7 @@ module ForemanHooks
 
       # Find any orchestration related hooks and register in those classes
       ForemanHooks::HooksObserver.hooks.each do |klass,events|
-        orchestrate = false
-        events.keys.each do |event|
-          orchestrate = true if ['create', 'update', 'destroy'].include? event
-        end
+        orchestrate = events.keys.detect { |event| ['create', 'update', 'destroy'].include? event }
         klass.send(:include, ForemanHooks::OrchestrationHook) if orchestrate
       end
     end

data/lib/foreman_hooks/orchestration_hook.rb

@@ -53,7 +53,7 @@ module ForemanHooks::OrchestrationHook
     end
 
     def hook_execute_set
-      @obj.exec_hook(@filename, @event, *args)
+      @obj.exec_hook(@filename, @event == 'destroy' ? 'create' : @event, *args)
     end
 
     def hook_execute_del

data/lib/foreman_hooks/util.rb

@@ -63,14 +63,25 @@ module ForemanHooks::Util
   def exec_hook(*args)
     logger.debug "Running hook: #{args.join(' ')}"
     success = if defined? Bundler && Bundler.responds_to(:with_clean_env)
-                Bundler.with_clean_env { system(*args) }
+                Bundler.with_clean_env { exec_hook_int(self.to_json, *args) }
               else
-                system(*args)
-              end
+                exec_hook_int(self.to_json, *args)
+              end.success?
 
     unless success
       logger.warn "Hook failure running `#{args.join(' ')}`: #{$?}"
     end
     success
   end
+
+  def exec_hook_int(stdin_data, *args)
+    output = nil
+    IO.popen(args.push(:err=>[:child, :out]), mode='r+') do |io|
+      io.write(stdin_data)
+      io.close_write
+      output = io.read
+    end
+    logger.debug "Hook output: #{output}" if output && !output.empty?
+    $?
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foreman_hooks
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-24 00:00:00.000000000 Z
+date: 2013-04-06 00:00:00.000000000 Z
 dependencies: []
 description: Plugin engine for Foreman that enables running custom hook scripts on
   Foreman events
@@ -28,6 +28,8 @@ files:
 - README.md
 - Rakefile
 - TODO
+- examples/hook_functions.sh
+- examples/log.sh
 - foreman_hooks.gemspec
 - lib/foreman_hooks.rb
 - lib/foreman_hooks/engine.rb