About Resources

A resource is a statement of configuration policy that:

• Describes the desired state for a configuration item
• Declares the steps needed to bring that item to the desired state
• Specifies a resource type—such as package, template, or service
• Lists additional details (also known as resource properties), as necessary
• Are grouped into recipes, which describe working configurations

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.

The Chef::Platform class maps providers to platforms (and platform versions). At the beginning of every chef-client run, Ohai 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:

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 directory["/tmp/folder"] resource, 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) properties (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

Every resource has its own set of actions and properties. Most properties have default values. Some properties are available to all resources, for example those used to send notifications to other resources and guards that help ensure that some resources are idempotent.

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'
  action :install
end

All actions have a default value. Only non-default behaviors of actions and properties need to be specified. For example, the package resource’s default action is :install and the name of the package defaults to the name of the resource. Therefore, it is possible to write a resource block that installs the latest tar.gz package like this:

package 'tar'

and a resource block that installs a tar.gz package for version 1.6.1 like this:

package 'tar' do
  version '1.16.1'
end

In both cases, the chef-client will use the default action (:install) to install the tar package.

Common Functionality

All resources (including custom resources) share a set of common actions, properties, conditional executions, notifications, and relative path options.

Common Item	Description
Actions	The :nothing action can be used with any resource or custom resource.
Properties	The ignore_failure, provider, retries, retry_delay, and supports properties can be used with any resource or custom 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 in Compile Phase	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. “are available from the chef-client directly and do not require a cookbook”):

Resource	Description
apt_package	Use the apt_package resource to manage packages for the Debian and Ubuntu platforms.
bash	Use the bash resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to 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 not_if and only_if to guard this resource for idempotence. 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.
batch	Use the batch resource to execute a batch script using the cmd.exe interpreter. The batch resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command inline. This resource inherits actions (:run and :nothing) and properties (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 not_if and only_if to guard this resource for idempotence.
bff_package	Use the bff_package resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources. Note A Backup File Format (BFF) package may not have a .bff file extension. The chef-client will still identify the correct provider to use based on the platform, regardless of the file extension.
breakpoint	Use the breakpoint resource to add breakpoints to recipes. Run the chef-shell in chef-client mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the chef-client during an actual chef-client run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server.
chef_gem	Use the chef_gem resource 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 properties and options as the gem_package resource, but does not accept the gem_binary property 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	Use the cookbook_file resource to transfer files from a sub-directory of COOKBOOK_NAME/files/ to a specified path located on a host that is running the chef-client. The file 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 in the COOKBOOK_NAME/files/default sub-directory may be used on any platform.
cron	Use the cron resource to manage cron entries for time-based job scheduling. Properties 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	Use the csh resource to execute scripts using the csh interpreter. This resource may also use any of the actions and properties that are available to 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 not_if and only_if to guard this resource for idempotence. 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.
deploy	Use the deploy resource to manage and control deployments. This is a popular resource, but is also complex, having the most properties, multiple providers, the added complexity of callbacks, plus four attributes that support layout modifications from within a recipe.
directory	Use the directory resource 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 property to specify the path to a location in a directory. Typically, permission to access that location in the directory is required.
dpkg_package	Use the dpkg_package resource 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.
dsc_script	Many DSC resources are comparable to built-in Chef resources. For example, both DSC and Chef have file, package, and service resources. The dsc_script resource is most useful for those DSC resources that do not have a direct comparison to a resource in Chef, such as the Archive resource, a custom DSC resource, an existing DSC script that performs an important task, and so on. Use the dsc_script resource to embed the code that defines a DSC configuration directly within a Chef recipe.
easy_install_package	Use the easy_install_package resource to manage packages for the Python platform.
env	Use the env resource 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	Use the erl_call resource 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 not_if and only_if to guard this resource for idempotence.
execute	Use the execute resource to execute a single 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 not_if and only_if to guard this resource for idempotence.
file	Use the file resource to manage files directly on a node.
freebsd_package	Use the freebsd_package resource to manage packages for the FreeBSD platform.
dpkg_package	Use the gem_package resource 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	Use the git resource 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	Use the group resource to manage a local group.
homebrew_package	Use the homebrew_package resource to manage packages for the Mac OS X platform.
http_request	Use the http_request resource to send an HTTP request (GET, PUT, POST, DELETE, HEAD, or OPTIONS) with an arbitrary message. This resource is often useful when custom callbacks are necessary.
ifconfig	Use the ifconfig resource to manage interfaces.
ips_package	Use the ips_package resource to manage packages (using Image Packaging System (IPS)) on the Solaris 11 platform.
link	Use the link resource to create symbolic or hard links.
log	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.
macports_package	Use the macports_package resource to manage packages for the Mac OS X platform.
mdadm	Use the mdadm resource 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	Use the mount resource to manage a mounted file system.
ohai	Use the ohai resource to reload the Ohai configuration on a node. This allows recipes that change system attributes (like a recipe that adds a user) to refer to those attributes later on during the chef-client run.
package	Use the package resource 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	Use the pacman_package resource to manage packages (using pacman) on the Arch Linux platform.
perl	Use the perl resource to execute scripts using the Perl interpreter. This resource may also use any of the actions and properties that are available to 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 not_if and only_if to guard this resource for idempotence. 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.
portage_package	Use the portage_package resource to manage packages for the Gentoo platform.
powershell_script	Use the powershell_script resource 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. The powershell_script resource creates and executes a temporary file (similar to how the script resource behaves), rather than running the command 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 not_if and only_if to guard this resource for idempotence.
python	Use the python resource to execute scripts using the Python interpreter. This resource may also use any of the actions and properties that are available to 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 not_if and only_if to guard this resource for idempotence. 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.
reboot	Use the reboot resource to reboot a node, a necessary step with some installations on certain platforms. This resource is supported for use on the Microsoft Windows, Mac OS X, and Linux platforms.
registry_key	Use the registry_key resource to create and delete registry keys in Microsoft Windows.
remote_directory	Use the remote_directory resource to 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	Use the remote_file resource to transfer a file from a remote location using file specificity. This resource is similar to the file resource.
route	Use the route resource to manage the system routing table in a Linux environment.
rpm_package	Use the rpm_package resource to manage packages for the RPM Package Manager platform.
ruby	Use the ruby resource to execute scripts using the Ruby interpreter. This resource may also use any of the actions and properties that are available to 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 not_if and only_if to guard this resource for idempotence. 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.
ruby_block	Use the ruby_block resource 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	Use the script resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby. This resource may also use any of the actions and properties that are available to 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 not_if and only_if to guard this resource for idempotence. 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.
service	Use the service resource to manage a service.
smart_os_package	Use the smartos_package resource to manage packages for the SmartOS platform.
solaris_package	The solaris_package resource is used to manage packages for the Solaris platform.
subversion	Use the subversion resource to manage source control resources that exist in a Subversion repository.
template	Use the template resource to manage the contents of a file using an Embedded Ruby (ERB) template by transferring files from a sub-directory of COOKBOOK_NAME/templates/ to a specified path located on a host that is running the chef-client. This resource includes actions and properties 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	Use the user resource 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 system 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 system 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 the system attributes during the current chef-client run.
windows_package	Use the windows_package resource to manage Microsoft Installer Package (MSI) packages for the Microsoft Windows platform.
windows_service	Use the windows_service resource to manage a service on the Microsoft Windows platform.
yum_package	Use the yum_package resource 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.

In addition, the chef_handler resource is configured and run using the chef_handler cookbook, which is the location in which custom handlers are defined and maintained. Despite being defined in a cookbook (as a custom resource), the chef_handler resource should otherwise be considered a “platform resource”.