A resource is a key part of a recipe that defines the actions that can be taken against a piece of the system. These actions are identified during each chef-client run as the resource collection is compiled. Once identified, each resource (in turn) is mapped to a provider, which then configures each piece of the system.
The chef_gem and gem_package resources are both used to install Ruby gems. For any machine on which the chef-client is installed, there are two instances of Ruby. One is the standard, system-wide instance of Ruby and the other is a dedicated instance that is available only to the chef-client. Use the chef_gem resource to install gems into the instance of Ruby that is dedicated to the chef-client. Use the gem_package resource to install all other gems (i.e. install gems system-wide).
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.
In many cases, it is better to use the package resource instead of this one. This is because when the package resource is used in a recipe, the chef-client will use details that are collected by Ohai at the start of the chef-client run to determine the correct package application. Using the package resource allows a recipe to be authored in a way that allows it to be used across many platforms. That said, there are scenarios where using an application-specific package is preferred.
The syntax for using the gem_package resource in a recipe is as follows:
gem_package "name" do attribute "value" # see attributes section below ... action :action # see actions section below end
The RubyGems package provider attempts to use the RubyGems API to install gems without spawning a new process, whenever possible. A gems command to install will be spawned under the following conditions:
If an explicit gem_binary parameter is not being used with the gem_package resource, it is preferable to provide the install options as a hash. This approach allows the provider to install the gem without needing to spawn an external gem process.
The following RubyGems options are available for inclusion within a hash and are passed to the RubyGems DependencyInstaller:
For more information about these options, see the RubyGems documentation: http://rubygems.rubyforge.org/rubygems-update/Gem/DependencyInstaller.html.
gem_package "bundler" do options(:prerelease => true, :format_executable => false) end
When using an explicit gem_binary, options must be passed as a string. When not using an explicit gem_binary, the chef-client is forced to spawn a gems process to install the gems (which uses more system resources) when options are passed as a string. String options are passed verbatim to the gems command and should be specified just as if they were passed on a command line. For example, --prerelease for a pre-release gem.
gem_package "nokogiri" do gem_binary("/opt/ree/bin/gem") options("--prerelease --no-format-executable") end
Options can be specified in a .gemrc file. By default the gem_package resource will use the Ruby interface to install gems which will ignore the .gemrc file. The gem_package resource can be forced to use the gems command instead (and to read the .gemrc file) by adding the gem_binary attribute to a code block.
gem_package "nokogiri" do gem_binary "gem" end
This resource has the following actions:
|:install||Default. Use to install a package. If a version is specified, use to install the specified version of a package.|
|:upgrade||Use to install a package and/or to ensure that a package is the latest version.|
|:reconfig||Use to reconfigure a package. This action requires a response file.|
|:remove||Use to remove a package.|
|:purge||Use to purge a package. This action typically removes the configuration files as well as the package.|
This resource has the following attributes:
|gem_binary||An attribute for the gem_package provider that is used to specify a gems binary. This attribute is useful when installing Ruby 1.9 gems while running in Ruby 1.8. By default, the same version of Ruby that is used by the chef-client will be installed.|
|options||One (or more) additional options that are passed to the command.|
|package_name||The name of the package. Default value: the name of the resource block (see Syntax section above).|
|provider||Optional. Use to specify a provider by using its long name. For example: provider Chef::Provider::Long::Name. See the Providers section below for the list of providers available to this resource.|
|response_file||Optional. The response file used to pre-seed a package. Default value: nil.|
|source||Optional. The package source for providers that use a local file.|
|version||The version of a package to be installed or upgraded. Default value: nil.|
The following providers are available. Use the short name to call the provider from a recipe:
|Long name||Short name||Notes|
|Chef::Provider::Package||package||When this short name is used, the chef-client will attempt to determine the correct provider during the chef-client run.|
|Chef::Provider::Package::Rubygems||gem_package||Can be used with the options attribute.|
The following examples demonstrate various approaches for using resources in recipes. If you want to see examples of how Opscode uses resources in recipes, take a closer look at the cookbooks that Opscode authors and maintains: https://github.com/opscode-cookbooks.
Install a gems file from the local file system
gem_package "right_aws" do source "/tmp/right_aws-1.11.0.gem" action :install end
Use the ignore_failure common attribute
gem_package "syntax" do action :install ignore_failure true end