Chef

Table Of Contents

About Resources and Providers

Note

If you want to see all of the information about resources in a single document, see: http://docs.opscode.com/chef/resources.html. Keep reading this page for topics about individual resources.

A resource is a key part of a recipe. A resource defines the actions that can be taken, such as when a package should be installed, whether a service should be enabled or restarted, which groups, users, or groups of users should be created, where to put a collection of files, what the name of a new directory should be, and so on. During a chef-client run, each resource is identified and then associated with a provider. The provider then does the work to complete the action defined by the resource. Each resource is processed in the same order as they appear in a recipe. The chef-client ensures that the same actions are taken the same way everywhere and that actions produce the same result every time. A resource is implemented within a recipe using Ruby.

Where a resource represents a piece of the system (and its desired state), a provider defines the steps that are needed to bring that piece of the system from its current state into the desired state. These steps are de-coupled from the request itself. The request is made in a recipe and is defined by a lightweight resource. The steps are then defined by a lightweight provider.

The Chef::Platform class maps providers to platforms (and platform versions). Ohai, as part of every chef-client run, verifies the platform and platform_version attributes on each node. The chef-client then uses those values to identify the correct provider, build an instance of that provider, identify the current state of the resource, do the specified action, and then mark the resource as updated (if changes were made). For example, given the following resource:

directory "/tmp/folder" do
  owner "root"
  group "root"
  mode 0755
  action :create
end

The chef-client will look up the provider for the directory resource, which happens to be Chef::Provider::Directory, call load_current_resource to create a new resource called directory["/tmp/folder"], and then, based on the current state of the directory, do the specified action, which in this case is to create a directory called /tmp/folder. If the directory already exists, nothing will happen. If the directory was changed in any way, the resource is marked as updated.

Resources Syntax

A resource is a Ruby block with four components: a type, a name, one (or more) attributes (with values), and one (or more) actions. The syntax for a resource is like this:

type "name" do
   attribute "value"
   action :type_of_action
end

For example, a resource that is used to install a tar.gz package for version 1.16.1 may look something like this:

package "tar" do
  version "1.16.1-1"
  action :install
end

Every resource has its own set of actions and attribute. Most attributes have default values. Some attributes are available to all resources, for example some attributes are used to send notifications to other resources, whereas others are used to set up conditional execution rules.

All actions have a default value. Only non-default behaviors of actions and attributes need to be specified. For example, the package resource’s default action is to install and the name of the package defaults to the "name" of the resource, therefore it is possible to write a resource block like this:

package "tar"

and the chef-client will use the default action (:install) to install the tar package.

Note

The attribute keyword associated with resources in the LWRP DSL is not the same as the ‘attributes’ that make up node objects

Common Functionality

All resources share a set of common actions, attributes, conditional executions, notifications, and relative path options.

Common Item Description
Actions The :nothing action can be used with any resource or lightweight resource.
Attributes The ignore_failure, provider, retries, retry_delay, and supports attributes can be used with any resource or lightweight resources.
Guards The not_if and only_if conditional executions can be used to put additional guards around certain resources so that they are only run when the condition is met.
Notifications The notifies and subscribes notifications can be used with any resource.
Relative Paths The #{ENV['HOME']} relative path can be used with any resource.
Windows File Security The template, file, remote_file, cookbook_file, directory, and remote_directory resources support the use of inheritance and access control lists (ACLs) within recipes.
Run a Resource during Resource Compilation Sometimes a resource needs to be run before every other resource or after all resources have been added to the resource collection.

Resources

The following resources are platform resources (i.e. “built into the chef-client”):

Resource Description
apt_package The apt_package resource is used to manage packages for the Debian and Ubuntu platforms.
bash

The bash resource is used to execute scripts using the Bash interpreter and includes all of the actions and attributes that are available to the execute resource.

Note

The bash script resource (which is based on the script resource) is different from the ruby_block resource because Ruby code that is run with this resource is created as a temporary file and executed like other script resources, rather than run inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.

batch The batch resource for the Microsoft Windows platform is used to execute a batch script using the cmd.exe interpreter. The batch creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. This resource inherited actions (:run and :nothing) and attributes (creates, cwd, environment, group, path, timeout, and user) from the execute resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.
breakpoint The breakpoint resource is used to add breakpoints to recipes in the same way as any other resource. When the chef-client is run in chef-shell mode, those breakpoints can be used to debug recipes. Breakpoints are ignored by the chef-client during an actual chef-client run. In general, breakpoints are used most often in a non-production environment, for the purpose of debugging recipes. After those recipes are debugged and the desired behavior has been tested, the breakpoints are typically removed from the recipes before uploading the cookbooks to a production environment (even if the chef-client ignores them when building the resource collection during an official chef-client run).
chef_gem

The chef_gem resource is used to install a gem only for the instance of Ruby that is dedicated to the chef-client. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources.

The chef_gem resource works with all of the same attributes and options as the gem_package resource, but does not accept the gem_binary attribute because it always uses the CurrentGemEnvironment under which the chef-client is running. In addition to performing actions similar to the gem_package resource, the chef_gem resource does the following:

  • Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is installed
  • Runs Gem.clear_paths after the action, ensuring that gem is aware of changes so that it can be required immediately after it is installed
cookbook_file The cookbook_file resource is used to transfer files from a sub-directory of the files/ directory in a cookbook to a specified path that is located on the host running the chef-client or chef-solo. The file in a cookbook is selected according to file specificity, which allows different source files to be used based on the hostname, host platform (operating system, distro, or as appropriate), or platform version. Files that are located under COOKBOOK_NAME/files/default can be used on any platform.
cron

The cron resource is used to manage cron entries for time-based job scheduling. Attributes for a schedule will default to * if not provided. The cron resource requires access to a crontab program, typically cron.

Warning

The cron resource should only be used to modify an entry in a crontab file. Use the cookbook_file or template resources to add a crontab file to the cron.d directory. The cron_d lightweight resource (found in the cron cookbook) is another option for managing crontab files.

csh

The csh resource is used to execute scripts using the csh interpreter and includes all of the actions and attributes that are available to the execute resource.

Note

The csh script resource (which is based on the script resource) is different from the ruby_block resource because Ruby code that is run with this resource is created as a temporary file and executed like other script resources, rather than run inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.

deploy The deploy resource is used to manage and control deployments. This is a popular resource, but is also complex, having the most attributes, multiple providers, the added complexity of callbacks, plus four attributes that support layout modifications from within a recipe.
directory The directory resource is used to manage a directory, which is a hierarchy of folders that comprises all of the information stored on a computer. The root directory is the top-level, under which the rest of the directory is organized. The directory resource uses the name attribute to specify the path to a location in a directory. Typically, permission to access that location in the directory is required.
dpkg_package The dpkg_package resource is used to manage packages for the dpkg platform. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources.
easy_install_package The easy_install_package resource is used to manage packages for the Python platform.
env The env resource is used to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler.
erl_call The erl_call resource is used to connect to a node located within a distributed Erlang system. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.
execute The execute resource is used to execute a command. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.
file The file resource is used to manage files that are present on a node, including setting or updating the contents of those files.
freebsd_package The freebsd_package resource is used to manage packages for the FreeBSD platform.
gem_package The gem_package resource is used to manage gem packages that are only included in recipes. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources.
git The git resource is used to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource.
group The group resource is used to manage a local group.
http_request The http_request resource is used to send an HTTP request (GET, PUT, POST, DELETE, HEAD, or OPTIONS) with an arbitrary message. This resource is useful when custom callbacks are necessary.
ifconfig The ifconfig resource is used to manage interfaces.
ips_package The ips_package resource is used to manage packages (using Image Packaging System (IPS)) on the Solaris 11 platform.
link The link resource is used to create symbolic or hard links.
log The log resource is used to create log entries from a recipe.
macports_package The macports_package resource is used to manage packages for the Mac OS X platform.
mdadm The mdadm resource is used to manage RAID devices in a Linux environment using the mdadm utility. The mdadm provider will create and assemble an array, but it will not create the config file that is used to persist the array upon reboot. If the config file is required, it must be done by specifying a template with the correct array layout, and then by using the mount provider to create a file systems table (fstab) entry.
mount The mount resource is used to manage a mounted file system.
ohai The ohai resource is used to reload the Ohai configuration on a node, which allows recipes that change system attributes (like adding a user) to refer to those attributes later on during the chef-client run.
package The package resource is used to manage packages. When the package is installed from a local file (such as with RubyGems, dpkg, or RPM Package Manager), the file must be added to the node using the remote_file or cookbook_file resources.
pacman_package The pacman_package resource is used to manage packages (using pacman) on the Arch Linux platform.
perl

The perl resource is used to execute scripts using the Perl interpreter and includes all of the actions and attributes that are available to the execute resource.

Note

The perl script resource (which is based on the script resource) is different from the ruby_block resource because Ruby code that is run with this resource is created as a temporary file and executed like other script resources, rather than run inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.

portage_package The portage_package resource is used to manage packages for the Gentoo platform.
powershell_script The powershell_script resource is a resource for the Microsoft Windows platform that is used to execute a script using the Windows PowerShell interpreter, much like how the script and script-based resources—bash, csh, perl, python, and ruby—are used. The powershell_script is specific to the Microsoft Windows platform and the Windows PowerShell interpreter. This resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. This resource includes actions (:run and :nothing; ) and attributes (creates, cwd, environment, group, path, timeout, and user) that are inherited from the execute resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.
python

The python resource is used to execute scripts using the Python interpreter and includes all of the actions and attributes that are available to the execute resource.

Note

The python script resource (which is based on the script resource) is different from the ruby_block resource because Ruby code that is run with this resource is created as a temporary file and executed like other script resources, rather than run inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.

registry_key

The registry_key resource is used to create and delete registry keys in Microsoft Windows.

64-bit versions of Microsoft Windows have a 32-bit compatibility layer in the registry that reflects and redirects certain keys (and their sub-keys) into specific locations. By default, the registry functionality will default to the machine architecture of the system that is being configured. The chef-client can access any reflected or redirected registry key. The chef-client can write to any 64-bit registry location. (This behavior is not affected by the chef-client running as a 32-bit application.) For more information, see: http://msdn.microsoft.com/en-us/library/windows/desktop/aa384235(v=vs.85).aspx.

remote_directory The remote_directory resource is used incrementally transfer a directory from a cookbook to a node. The directory that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY. The remote_directory resource will obey file specificity.
remote_file The remote_file resource is used to transfer a file from a remote location using file specificity. This resource is similar to the file resource.
route The route resource is used to manage the system routing table in a Linux environment.
rpm_package The rpm_package resource is used to manage packages for the RPM Package Manager platform.
ruby

The ruby resource is used to execute scripts using the Ruby interpreter and includes all of the actions and attributes that are available to the execute resource.

Note

The ruby script resource (which is based on the script resource) is different from the ruby_block resource because Ruby code that is run with this resource is created as a temporary file and executed like other script resources, rather than run inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.

ruby_block The ruby_block resource is used to execute Ruby code during a chef-client run. Ruby code in the ruby_block resource is evaluated with other resources during convergence, whereas Ruby code outside of a ruby_block resource is evaluated before other resources, as the recipe is compiled.
script

The script resource is used to execute scripts using the specified interpreter (Bash, csh, Perl, Python, or Ruby) and includes all of the actions and attributes that are available to the execute resource.

Note

The script resource is different from the ruby_block resource because Ruby code that is run with this resource is created as a temporary file and executed like other script resources, rather than run inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use the not_if and only_if meta parameters to guard the use of this resource for idempotence.

service The service resource is used to manage a service.
smart_o_s_package The smartos_package resource is used to manage packages for the SmartOS platform.
solaris_package The solaris_package resource is used to manage packages for the Solaris platform.
subversion The subversion resource is used to manage source control resources that exist in a Subversion repository.
template The template resource is used to manage file contents with an embedded Ruby (erb) template. This resource includes actions and attributes from the file resource. Template files managed by the template resource follow the same file specificity rules as the remote_file and file resources.
user

The user resource is used to add users, update existing users, remove users, and to lock/unlock user passwords.

Note

System attributes are collected by Ohai at the start of every chef-client run. By design, the actions available to the user resource are processed after the start of the chef-client run. This means that attributes added or modified by the user resource during the chef-client run must be reloaded before they can be available to the chef-client. These attributes can be reloaded in two ways: by picking up the values at the start of the (next) chef-client run or by using the ohai resource to reload these attributes during the current chef-client run.

yum_package The yum_package resource is used to install, upgrade, and remove packages with yum for the Red Hat and CentOS platforms. The yum_package resource is able to resolve provides data for packages much like yum can do when it is run from the command line. This allows a variety of options for installing packages, like minimum versions, virtual provides, and library names.