Table Of Contents

About Definitions

A definition is code that is reused across recipes, similar to a compile-time macro. A definition is created using arbitrary code wrapped around built-in chef-client resources—file, execute, template, and so on—by declaring those resources into the definition as if they were declared in a recipe. A definition is then used in one (or more) recipes as if it were a resource.

Though a definition behaves like a resource, some key differences exist. A definition:

  • Is not a resource or a lightweight resource
  • Is defined from within the /definitions directory of a cookbook
  • Is loaded before resources during the chef-client run; this ensures the definition is available to all of the resources that may need it
  • May not notify resources in the resource collection because a definition is loaded before the resource collection itself is created; however, a resource in a definition may notify a resource that exists within the same definition
  • Automatically supports why-run mode, unlike lightweight resources

Use a defintion when repeating patterns exist across resources and/or when a simple, direct approach is desired. There is no limit to the number of resources that may be included in a definition: use as many built-in chef-client resources as necessary.


A definition has four components:

  • A resource name
  • Zero or more arguments that define parameters their default values; if a default value is not specified, it is assumed to be nil
  • A hash that can be used within a definition’s body to provide access to parameters and their values
  • The body of the definition

The basic syntax of a definition is:

define :resource_name do

More commonly, the usage incorporates arguments to the definition:

define :resource_name, :parameter => :argument, :parameter => :argument do
  body (likely referencing the params hash)

The following simplistic example shows a definition with no arguments (a parameter-less macro in the truest sense):

define :prime_myfile do
  file "/etc/myfile" do
    content "some content"

An example showing the more common usage pattern, a definition named apache_site with an parameter called action with an argument for enable, would look something like:

define :apache_site, :action => :enable do
  if params[:action] == :enable

Or the following definition, which looks like a resource when used in a recipe, but also contains resources—directory and file—that are repeated, but with slightly different parameters:

define :host_porter, :port => 4000, :hostname => nil do
  params[:hostname] ||= params[:name]

  directory "/etc/#{params[:hostname]}" do
    recursive true

  file "/etc/#{params[:hostname]}/#{params[:port]}" do
    content "some content"

which is then used in a recipe like this:

host_porter node['hostname'] do
 port 4000

host_porter "www1" do
  port 4001


The following examples show how to use cookbook definitions.

Simplify Repeating Patterns

A definition file is similar to a macro; use a definition to define reusable code. For example, the following definition defines a common installation scenario, in this case installing Splunk on multiple machines:

define :splunk_installer, :url => nil do
  cache_dir = Chef::Config[:file_cache_path]
  package_file = splunk_file(params[:url])
  cached_package = ::File.join(cache_dir, package_file)

  remote_file cached_package do
    source params[:url]
    action :create_if_missing

  if %w{omnios}.include?(node['platform'])
    pkgopts = [
      "-a #{cache_dir}/#{params[:name]}-nocheck",
      "-r #{cache_dir}/splunk-response"

    execute "uncompress #{cached_package}" do
      not_if { ::File.exists?("#{cache_dir}/#{package_file.gsub(/\.Z/, '')}") }

    cookbook_file "#{cache_dir}/#{params[:name]}-nocheck" do
      source 'splunk-nocheck'

    file "#{cache_dir}/splunk-response" do
      content 'BASEDIR=/opt'

  package params[:name] do
    source cached_package.gsub(/\.Z/, '')
    case node['platform_family']
    when 'rhel'
      provider Chef::Provider::Package::Rpm
    when 'debian'
      provider Chef::Provider::Package::Dpkg
    when 'omnios'
      provider Chef::Provider::Package::Solaris
      options pkgopts.join(' ')

Once created, this definition is used just like a resource:

splunk_installer 'use #1' do
  url node['splunk']['server']['url']

and then another recipe:

splunk_installer 'use #2' do
  url node['splunk']['forwarder']['url']

and so on.

Create a Resource

A definition file can be used to create an object that the chef-client can then use like a resource. For example:

apache_site Definition
define :apache_site, :enable => true do
  include_recipe "apache2"

  if params[:enable]
    execute "a2ensite #{params[:name]}" do
      command "/usr/sbin/a2ensite #{params[:name]}"
      notifies :restart, resources(:service => "apache2")
      not_if do
        ::File.symlink?("#{node[:apache][:dir]}/sites-enabled/#{params[:name]}") or
      only_if do ::File.exists?("#{node[:apache][:dir]}/sites-available/#{params[:name]}") end
    execute "a2dissite #{params[:name]}" do
      command "/usr/sbin/a2dissite #{params[:name]}"
      notifies :restart, resources(:service => "apache2")
      only_if do ::File.symlink?("#{node[:apache][:dir]}/sites-enabled/#{params[:name]}") end

Once created, the definition can be used by placing it in a recipe:

apache_site resource
# Enable my_site.conf
apache_site "my_site.conf" do
  enable true

# Disable my_site.conf
apache_site "my_site.conf" do
  enable false

The attributes of the new apache_site object are made accessible with the params hash. Within the context of a chef-client run, the definition will be replaced by all the resources that are specified within the definition. For example, in the enabled case, the definition will be expanded to:

execute "a2ensite my_site.conf" do
  command "/usr/sbin/a2ensite my_site.conf"
  notifies :restart, resources(:service => "apache2")
  not_if do
    ::File.symlink?("/etc/apache2/sites-enabled/my_site.conf") or

Many Recipes, One Definition

Data can be passed to a definition from more than one recipe. For example, when both /etc/aliases and /etc/sudoers require updates from multiple recipes during a single chef-client run. A definition file that reopens resources would look something like:

# example provided by community member "Mithrandir". Thank you!

define :email_alias, :recipients => [] do
  execute "newaliases" do
    action :nothing

  t = nil
    t = resources(:template => "/etc/aliases")
  rescue Chef::Exceptions::ResourceNotFound
    t = template "/etc/aliases" do
      source "aliases.erb"
      cookbook "aliases"
      variables({:aliases => {} })
      notifies :run, "execute[newaliases]"

  if not t.variables[:aliases].has_key?(params[:name])
    t.variables[:aliases][params[:name]] = []
  t.variables[:aliases][params[:name]] << [ params[:recipients] ]

Virtual Hosts

Two applications need to be deployed and run on a single node under the same domain and sub-domain. A Ruby on Rails application will reside as the main application at and a WordPress application will reside at The domain is running Apache2 as the web server. The domain is expected to grow, but for now only two run_list resources are created, with the appropriate roles added to them. At some point in the future, when a new sub-domain is required, a new run_list resource would also be created.

The virtual host on the Apache2 server is only one per node, which can create challenges when a node requires updates. Using a definition helps get around this issue. For example, the web_app definition exists in the apache2 cookbook, and can be used like this:

web_app "blog_site" do
  server_name "blog"
  server_aliases [ "blog.#{node['domain']}", node['fqdn'] ]
  docroot "/srv/www/blog_site"

When the chef-client processes a recipe that contains this definition, it will find the web_app resource and will attempt to recognize it as a resource. Assuming that the apache2 cookbook is available, the resources contained within that cookbook will be found and loaded, replacing the definition.