chef_handler Resource
This page is generated from the Chef Infra Client source code.To suggest a change, edit the chef_handler.rb file and submit a pull request to the Chef Infra Client repository.
Use the chef_handler resource to enable handlers during a Chef Infra Client run. The resource allows arguments to be passed to Chef Infra Client, which then applies the conditions defined by the custom handler to the node attribute data collected during a Chef Infra Client run, and then processes the handler based on that data. The chef_handler resource is typically defined early in a node’s run-list (often being the first item). This ensures that all of the handlers will be available for the entire Chef Infra Client run.
New in Chef Infra Client 14.0.
Handler Types
There are three types of handlers:
- exception
An exception handler is used to identify situations that have caused a Chef Infra Client run to fail. An exception handler can be loaded at the start of a Chef Infra Client run by adding a recipe that contains the chef_handler resource to a node’s run-list. An exception handler runs when the
failed?
property for therun_status
object returnstrue
.- report
A report handler is used when a Chef Infra Client run succeeds and reports back on certain details about that Chef Infra Client run. A report handler can be loaded at the start of a Chef Infra Client run by adding a recipe that contains the chef_handler resource to a node’s run-list. A report handler runs when the
success?
property for therun_status
object returnstrue
.- start
A start handler is used to run events at the beginning of a Chef Infra Client run. A start handler can be loaded at the start of a Chef Infra Client run by adding the start handler to the
start_handlers
setting in the client.rb file or by installing the gem that contains the start handler by using the chef_gem resource in a recipe in the chef-client cookbook. (A start handler may not be loaded using thechef_handler
resource.)
Exception / Report
Exception and report handlers are used to trigger certain behaviors in response to specific situations, typically identified during a Chef Infra Client run.
- An exception handler is used to trigger behaviors when a defined aspect of a Chef Infra Client run fails.
- A report handler is used to trigger behaviors when a defined aspect of a Chef Infra Client run is successful.
Both types of handlers can be used to gather data about a Chef Infra Client run and can provide rich levels of data about all types of usage, which can be used later for trending and analysis across the entire organization.
Exception and report handlers are made available to a Chef Infra Client run in one of the following ways:
- By adding the chef_handler resource to a recipe, and then adding that recipe to the run-list for a node. (The chef_handler resource is available from the chef_handler cookbook.)
- By adding the handler to one of the following settings in the node’s
client.rb file:
exception_handlers
and/orreport_handlers
The chef_handler resource allows exception and report handlers to be enabled from within recipes, which can then added to the run-list for any node on which the exception or report handler should run. The chef_handler resource is available from the chef_handler cookbook.
To use the chef_handler resource in a recipe, add code similar to the following:
chef_handler 'name_of_handler' do
source '/path/to/handler/handler_name'
action :enable
end
For example, a handler for Growl needs to be enabled at the beginning of a Chef Infra Client run:
chef_gem 'chef-handler-growl'
and then is activated in a recipe by using the chef_handler resource:
chef_handler 'Chef::Handler::Growl' do
source 'chef/handler/growl'
action :enable
end
Start
A start handler is not loaded into a Chef Infra Client run from a
recipe, but is instead listed in the client.rb file using the
start_handlers
attribute. The start handler must be installed on the
node and be available to Chef Infra Client before the start of a Chef
Infra Client run. Use the chef-client cookbook to install the start
handler.
Start handlers are made available to a Chef Infra Client run in one of the following ways:
- By adding a start handler to the chef-client cookbook, which installs the handler on the node so that it is available to Chef Infra Client at the start of a Chef Infra Client run
- By adding the handler to one of the following settings in the node’s
client.rb file:
start_handlers
The chef-client cookbook can be configured to automatically install and configure gems that are required by a start handler. For example:
node.override['chef_client']['load_gems']['chef-reporting'] = {
require_name: 'chef_reporting',
action: :install,
}
node.override['chef_client']['config']['start_handlers'] = [
{
class: 'Chef::Reporting::StartHandler',
arguments: [],
},
]
include_recipe 'chef-client::config'
Syntax
A chef_handler resource block enables handlers during a chef-client
run. Two handlers—JsonFile
and ErrorReport
—are built into Chef:
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments :path => '/var/chef/reports'
action :enable
end
and:
chef_handler 'Chef::Handler::ErrorReport' do
source 'chef/handler/error_report'
action :enable
end
show how to enable those handlers in a recipe.
The full syntax for all of the properties that are available to the chef_handler resource is:
chef_handler 'name' do
arguments Array, Hash # default value: []
class_name String # default value: 'name' unless specified
source String
type Hash # default value: {"report"=>true, "exception"=>true}
action Symbol # defaults to :enable if not specified
end
where:
chef_handler
is the resource.name
is the name given to the resource block.action
identifies which steps Chef Infra Client will take to bring the node into the desired state.arguments
,class_name
,source
, andtype
are the properties available to this resource.
Actions
The chef_handler resource has the following actions:
:disable
- Disables the handler for the current Chef Infra Client run on the current node.
:enable
- Enables the handler for the current Chef Infra Client run on the current node. (default)
:nothing
- This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
Properties
The chef_handler resource has the following properties:
arguments
- Ruby Type: Array, Hash | Default Value:
[]
An array of arguments that are passed to the initializer for the handler class. For example:
arguments :key1 => ''val1''
or:
arguments [:key1 => ''val1'', :key2 => ''val2'']
class_name
- Ruby Type: String | Default Value:
The resource block's name
The name of the handler class. This can be module name-spaced.
source
- Ruby Type: String
The full path to the handler file. Can also be a gem path if the handler ships as part of a Ruby gem.
type
- Ruby Type: Hash | Default Value:
{"report"=>true, "exception"=>true}
The type of handler to register as, i.e. :report, :exception or both.
Common Resource Functionality
Chef resources include common properties, notifications, and resource guards.
Common Properties
The following properties are common to every resource:
compile_time
Ruby Type: true, false | Default Value:
false
Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the
compile phase
). Set to false to run while Chef Infra Client is configuring the node (theconverge phase
).ignore_failure
Ruby Type: true, false, :quiet | Default Value:
false
Continue running a recipe if a resource fails for any reason.
:quiet
will not display the full stack trace and the recipe will continue to run if a resource fails.retries
Ruby Type: Integer | Default Value:
0
The number of attempts to catch exceptions and retry the resource.
retry_delay
Ruby Type: Integer | Default Value:
2
The delay in seconds between retry attempts.
sensitive
Ruby Type: true, false | Default Value:
false
Ensure that sensitive resource data is not logged by Chef Infra Client.
Notifications
notifies
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may notify another resource to take action when its state changes. Specify a
'resource[name]'
, the:action
that resource should take, and then the:timer
for that action. A resource may notify more than one resource; use anotifies
statement for each resource to be notified.If the referenced resource does not exist, an error is raised. In contrast,
subscribes
will not fail if the source resource is not found.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for notifies
is:
notifies :action, 'resource[name]', :timer
subscribes
Ruby Type: Symbol, 'Chef::Resource[String]'
A resource may listen to another resource, and then take action if the
state of the resource being listened to changes. Specify a
'resource[name]'
, the :action
to be taken, and then the :timer
for
that action.
Note that subscribes
does not apply the specified action to the
resource that it listens to - for example:
file '/etc/nginx/ssl/example.crt' do
mode '0600'
owner 'root'
end
service 'nginx' do
subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately
end
In this case the subscribes
property reloads the nginx
service
whenever its certificate file, located under
/etc/nginx/ssl/example.crt
, is updated. subscribes
does not make any
changes to the certificate file itself, it merely listens for a change
to the file, and executes the :reload
action for its resource (in this
example nginx
) when a change is detected.
If the other resource does not exist, the subscription will not raise an
error. Contrast this with the stricter semantics of notifies
, which
will raise an error if the other resource does not exist.
A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
:before
Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
:delayed
Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
:immediate
,:immediately
Specifies that a notification should be run immediately, for each resource notified.
The syntax for subscribes
is:
subscribes :action, 'resource[name]', :timer
Guards
A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
- A string is executed as a shell command. If the command returns
0
, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a powershell_script run Windows PowerShell commands and may returntrue
in addition to0
. - A block is executed as Ruby code that must return either
true
orfalse
. If the block returnstrue
, the guard property is applied. If the block returnsfalse
, the guard property is not applied.
A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
PropertiesThe following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
not_if
Prevent a resource from executing when the condition returns
true
.only_if
Allow a resource to execute only if the condition returns
true
.
Examples
The following examples demonstrate various approaches for using the chef_handler resource in recipes:
Enable the ‘MyHandler’ handler
The following example shows how to enable a fictional ‘MyHandler’ handler which is located on disk at /etc/chef/my_handler.rb
. The handler will be configured to run with Chef Infra Client and will be passed values to the handler’s initializer method:
chef_handler 'MyHandler' do
source '/etc/chef/my_handler.rb' # the file should already be at this path
arguments path: '/var/chef/reports'
action :enable
end
Enable handlers during the compile phase
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments path: '/var/chef/reports'
action :enable
compile_time true
end
Handle only exceptions
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments path: '/var/chef/reports'
type exception: true
action :enable
end
Cookbook Versions (a custom handler)
@juliandunn created a custom report handler that logs all of the cookbooks and cookbook versions that were used during a Chef Infra Client run, and then reports after the run is complete.
cookbook_versions.rb:
The following custom handler defines how cookbooks and cookbook versions that are used during a Chef Infra Client run will be compiled into a report using the Chef::Log
class in Chef Infra Client:
require 'chef/log'
module Chef
class CookbookVersionsHandler < Chef::Handler
def report
cookbooks = run_context.cookbook_collection
Chef::Log.info('Cookbooks and versions run: #{cookbooks.map {|x| x.name.to_s + ' ' + x.version }}')
end
end
end
default.rb:
The following recipe is added to the run-list for every node on which a list of cookbooks and versions will be generated as report output after every Chef Infra Client run.
cookbook_file '/etc/chef/cookbook_versions.rb' do
source 'cookbook_versions.rb'
action :create
end
chef_handler 'Chef::CookbookVersionsHandler' do
source '/etc/chef/cookbook_versions.rb'
type report: true
action :enable
end
This recipe will generate report output similar to the following:
[2013-11-26T03:11:06+00:00] INFO: Chef Infra Client Run complete in 0.300029878 seconds
[2013-11-26T03:11:06+00:00] INFO: Running report handlers
[2013-11-26T03:11:06+00:00] INFO: Cookbooks and versions run: ["cookbook_versions_handler 1.0.0"]
[2013-11-26T03:11:06+00:00] INFO: Report handlers complete
JsonFile Handler
The JsonFile handler is available from the chef_handler
cookbook and can be used with exceptions and reports. It serializes run status data to a JSON file. This handler may be enabled in one of the following ways.
By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run:
require 'chef/handler/json_file'
report_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports')
exception_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports')
By using the chef_handler
resource in a recipe, similar to the following:
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments path: '/var/chef/reports'
action :enable
end
After it has run, the run status data can be loaded and inspected via Interactive Ruby (IRb):
irb(main):002:0> require 'json' => true
irb(main):003:0> require 'chef' => true
irb(main):004:0> r = JSON.parse(IO.read('/var/chef/reports/chef-run-report-20110322060731.json')) => ... output truncated
irb(main):005:0> r.keys => ['end_time', 'node', 'updated_resources', 'exception', 'all_resources', 'success', 'elapsed_time', 'start_time', 'backtrace']
irb(main):006:0> r['elapsed_time'] => 0.00246
Register the JsonFile handler
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file'
arguments path: '/var/chef/reports'
action :enable
end
ErrorReport Handler
The ErrorReport handler is built into Chef Infra Client and can be used for both exceptions and reports. It serializes error report data to a JSON file. This handler may be enabled in one of the following ways.
By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run:
require 'chef/handler/error_report'
report_handlers << Chef::Handler::ErrorReport.new
exception_handlers << Chef::Handler::ErrorReport.new
By using the chef_handler
resource in a recipe, similar to the following:
chef_handler 'Chef::Handler::ErrorReport' do
source 'chef/handler/error_report'
action :enable
end