Recipe Structure

A cookbook is primarily a set of recipes, which can perform a wide variety of tasks on an instance. To clarify how to implement recipes, it's useful to look at a simple example. The following is the setup recipe for the built-in HAProxy layer. Just focus on the overall structure at this point and don't worry too much about the details; they will be covered in the subsequent examples.

package 'haproxy' do
  action :install
end

if platform?('debian','ubuntu')
  template '/etc/default/haproxy' do
    source 'haproxy-default.erb'
    owner 'root'
    group 'root'
    mode 0644
  end
end

include_recipe 'haproxy::service'

service 'haproxy' do
  action [:enable, :start]
end

template '/etc/haproxy/haproxy.cfg' do
  source 'haproxy.cfg.erb'
  owner 'root'
  group 'root'
  mode 0644
  notifies :restart, "service[haproxy]"
end

The example highlights the key recipe elements, which are described in the following sections.

Resources

Recipes consist largely of a set of Chef resources. Each one specifies a particular aspect of the instance's final state, such as a package to be installed or a service to be started. The example has four resources:

Resources provide a declarative way to specify the instance state. Behind the scenes, each resource has an associated provider that performs the required tasks, such as installing packages, creating and configuring directories, starting services, and so on. If the details of the task depend on the particular operating system, the resource has multiple providers and uses the appropriate one for the system. For example, on a Red Hat Linux system the package provider uses yum to install packages. On a Ubuntu Linux system, the package provider uses apt-get.

You implement a resource as a Ruby code block with the following general format.

resource_type "resource_name" do
  attribute1 'value1'
  attribute2 'value2'
  ...
  action :action_name
  notifies : action 'resource'
end

The elements are:

Resources sometimes depend on operating system.

For descriptions of the standard resources, including the available attributes, actions, and notifications for each resource, see About Resources and Providers.

Flow Control

Because recipes are Ruby applications, you can use Ruby control structures to incorporate flow control into a recipe. For example, you can use Ruby conditional logic to have the recipe behave differently on different systems. The HAProxy recipe includes an if block that uses a template resource to create a configuration file, but only if the recipe is running on a Debian or Ubuntu system.

Another common scenario is using a loop to execute a resource multiple times with different attribute settings. For example, you can create a set of directories by using a loop to execute a directory resource multiple times with different directory names.

Included Recipes

include_recipe includes other recipes in your code, which allows you to modularize your recipes and reuse the same code in multiple recipes. When you run the host recipe, Chef replaces each include_recipe element with the specified recipe's code before it executes the host recipe. You identify an included recipe by using the standard Chef cookbook_name::recipe_name syntax, where recipe_name omits the .rb extension. The example includes one recipe, haproxy::service, which represents the HAProxy service.