Debug Recipes, chef-client Runs¶

Elements of good approaches to building cookbooks and recipes that are reliable include:

A consistent syntax pattern when constructing recipes
Using the same patterns in Ruby
Using platform resources before creating custom ones
Using community-authored resources before creating custom ones

Ideally, the best way to debug a recipe is to not have to debug it in the first place. That said, the following sections discuss various approaches to debugging recipes and failed chef-client runs.

Basic¶

Some simple ways to quickly identify common issues that can trigger recipe and/or chef-client run failures include:

Using an empty run-list
Using verbose logging with knife
Using logging with the chef-client
Using the log resource in a recipe to define custom logging

Empty Run-lists¶

Use an empty run-list to determine if a failed chef-client run has anything to do with the recipes that are defined within that run-list. This is a quick way to discover if the underlying cause of a chef-client run failure is a configuration issue. If a failure persists even if the run-list is empty, check the following:

Configuration settings in the config.rb file
Permissions for the user to both the Chef server and to the node on which the chef-client run is to take place

Knife¶

Use the verbose logging that is built into knife:

-V, --verbose: Set for more verbose outputs. Use -VV for maximum verbosity.

Note

Plugins do not always support verbose logging.

chef-client¶

Use the verbose logging that is built into the chef-client:

-l LEVEL, --log_level LEVEL: The level of logging to be stored in a log file.
-L LOGLOCATION, --logfile c: The location of the log file. This is recommended when starting any executable as a daemon. Default value: STDOUT.

log Resource¶

Use the log resource to create log entries. The log resource behaves like any other resource: built into the resource collection during the compile phase, and then run during the execution phase. (To create a log entry that is not built into the resource collection, use Chef::Log instead of the log resource.)

Note

By default, every log resource that executes will count as an updated resource in the updated resource count at the end of a Chef run. You can disable this behavior by adding count_log_resource_updates false to your Chef client.rb configuration file.

New in 12.0, -o RUN_LIST_ITEM. Changed in 12.0 -f no longer allows unforked intervals, -i SECONDS is applied before the chef-client run.

Syntax¶

A log resource block adds messages to the log file based on events that occur during the Chef Client run:

log 'message' do
  message 'A message add to the log.'
  level :info
end

The full syntax for all of the properties that are available to the log resource is:

log 'name' do
  level        Symbol # default value: info
  message      String # default value: 'name' unless specified
  action       Symbol # defaults to :write if not specified
end

where:

log is the resource.
name is the name given to the resource block.
action identifies which steps the chef-client will take to bring the node into the desired state.
level and message are the properties available to this resource.

Actions¶

The log resource has the following actions:

:nothing: Define this resource block to do nothing until notified by another resource to take action. When this resource is notified, this resource block is either run immediately or it is queued up to be run at the end of the Chef Client run.
:write: Default. Write to log.

Attributes¶

The log resource has the following properties:

ignore_failure

Ruby Type: true, false | Default Value: false

Continue running a recipe if a resource fails for any reason.

level

Ruby Type: Symbol | Default Value: :info

The logging level for displaying this message.. Options (in order of priority): :debug, :info, :warn, :error, and :fatal.

message

Ruby Type: String

The message to be added to a log file. Default value: the name of the resource block. See “Syntax” section above for more information.

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 a notifies statement for each resource to be notified.

A timer specifies the point during the Chef 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 the Chef Client run.
:immediate, :immediately: Specifies that a notification should be run immediately, per resource notified.

The syntax for notifies is:

notifies :action, 'resource[name]', :timer

retries

Ruby Type: Integer | Default Value: 0

The number of times to catch exceptions and retry the resource.

retry_delay

Ruby Type: Integer | Default Value: 2

The retry delay (in seconds).

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.

A timer specifies the point during the Chef 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 the Chef Client run.
:immediate, :immediately: Specifies that a notification should be run immediately, per resource notified.

The syntax for subscribes is:

subscribes :action, 'resource[name]', :timer

Providers¶

This resource has the following providers:

Chef::Provider::Log::ChefLog, log: The default provider for all platforms.

Examples¶

The following examples demonstrate various approaches for using resources in recipes. If you want to see examples of how Chef uses resources in recipes, take a closer look at the cookbooks that Chef authors and maintains: https://github.com/chef-cookbooks.

Specify a log entry

log 'a string to log'

Set debug logging level

log 'a debug string' do
  level :debug
end

Create log entry when the contents of a data bag are used

log 'a debug string' do
  level :debug
end

Add a message to a log file

log 'message' do
  message 'This is the message that will be added to the log.'
  level :info
end

Advanced¶

Some more complex ways to debug issues with a chef-client run include:

Using the chef_handler cookbook
Using the chef-shell and the breakpoint resource to add breakpoints to recipes, and to then step through the recipes using the breakpoints
Using the debug_value method from chef-shell to identify the location(s) from which attribute values are being set
Using the ignore_failure method in a recipe to force the chef-client to move past an error to see what else is going on in the recipe, outside of a known failure
Using chef-solo to run targeted chef-client runs for specific scenarios

chef_handler¶

Use a handler to identify situations that arise during a chef-client run, and then tell the chef-client how to handle these situations when they occur.

There are three types of handlers:

Handler	Description
exception	An exception handler is used to identify situations that have caused a chef-client run to fail. An exception handler can be loaded at the start of a chef-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 the `run_status` object returns `true`.
report	A report handler is used when a chef-client run succeeds and reports back on certain details about that chef-client run. A report handler can be loaded at the start of a chef-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 the `run_status` object returns `true`.
start	A start handler is used to run events at the beginning of the chef-client run. A start handler can be loaded at the start of a chef-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 the `chef_handler` resource.)

chef-shell¶

chef-shell is a recipe debugging tool that allows the use of breakpoints within recipes. chef-shell runs as an Interactive Ruby (IRb) session. chef-shell supports both recipe and attribute file syntax, as well as interactive debugging features.

chef-shell is tool that is run using an Interactive Ruby (IRb) session. chef-shell currently supports recipe and attribute file syntax, as well as interactive debugging features. chef-shell has three run modes:

Mode	Description
Standalone	Default. No cookbooks are loaded, and the run-list is empty.
Solo	chef-shell acts as a chef-solo client. It attempts to load the chef-solo configuration file and JSON attributes. If the JSON attributes set a run-list, it will be honored. Cookbooks will be loaded in the same way that chef-solo loads them. chef-solo mode is activated with the `-s` or `--solo` command line option, and JSON attributes are specified in the same way as for chef-solo, with `-j /path/to/chef-solo.json`.
Client	chef-shell acts as a chef-client. During startup, it reads the chef-client configuration file and contacts the Chef server to get attributes and cookbooks. The run-list will be set in the same way as normal chef-client runs. chef-client mode is activated with the `-z` or `--client` options. You can also specify the configuration file with `-c CONFIG` and the server URL with `-S SERVER_URL`.

Configure¶

chef-shell determines which configuration file to load based on the following:

If a configuration file is specified using the -c option, chef-shell will use the specified configuration file
When chef-shell is started using a named configuration as an argument, chef-shell will search for a chef-shell.rb file in that directory under ~/.chef. For example, if chef-shell is started using production as the named configuration, the chef-shell will load a configuration file from ~/.chef/production/chef_shell.rb
If a named configuration is not provided, chef-shell will attempt to load the chef-shell.rb file from the .chef directory. For example: ~/.chef/chef_shell.rb
If a chef-shell.rb file is not found, chef-shell will attempt to load the client.rb file
If a chef-shell.rb file is not found, chef-shell will attempt to load the solo.rb file

chef-shell.rb¶

The chef-shell.rb file can be used to configure chef-shell in the same way as the client.rb file is used to configure the chef-client. For example, to configure chef-shell to authenticate to the Chef server, copy the node_name, client_key, and chef_server_url settings from the config.rb file:

node_name                'your-knife-clientname'
client_key               File.expand_path('~/.chef/my-client.pem')
chef_server_url          'https://api.opscode.com/organizations/myorg'

and then add them to the chef-shell.rb file. Other configuration possibilities include disabling Ohai plugins (which will speed up the chef-shell boot process) or including arbitrary Ruby code in the chef-shell.rb file.

Run as a chef-client¶

By default, chef-shell loads in standalone mode and does not connect to the Chef server. The chef-shell can be run as a chef-client to verify functionality that is only available when the chef-client connects to the Chef server, such as search functionality or accessing data stored in data bags.

chef-shell can use the same credentials as knife when connecting to a Chef server. Make sure that the settings in chef-shell.rb are the same as those in config.rb, and then use the -z option as part of the command. For example:

$ chef-shell -z

Manage¶

When chef-shell is configured to access a Chef server, chef-shell can list, show, search for and edit cookbooks, clients, nodes, roles, environments, and data bags.

The syntax for managing objects on the Chef server is as follows:

$ chef-shell -z named_configuration

where:

named_configuration is an existing configuration file in ~/.chef/named_configuration/chef_shell.rb, such as production, staging, or test

Once in chef-shell, commands can be run against objects as follows:

$ chef (preprod) > items.command

items is the type of item to search for: cookbooks, clients, nodes, roles, environments or a data bag
command is the command: list, show, find, or edit

For example, to list all of the nodes in a configuration named “preprod”:

$ chef (preprod) > nodes.list