A resource defines the desired state for a single configuration item present on a node that is under management by Chef. A resource collection—one (or more) individual resources—defines the desired state for the entire node. During a chef-client run, the current state of each resource is tested, after which the chef-client will take any steps that are necessary to repair the node and bring it back into the desired state.
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).
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.
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.
A gem_package resource block manages a package on a node, typically by installing it. The simplest use of the gem_package resource is:
which will install the named package using all of the default options and the default action (:install).
The full syntax for all of the attributes that are available to the gem_package resource is:
gem_package 'name' do clear_sources TrueClass, FalseClass gem_binary String options String package_name String, Array # defaults to 'name' if not specified provider Chef::Provider::Package::Rubygems source String timeout String, Integer version String, Array action Symbol # defaults to :install if not specified 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.
A template named gemrc.erb is located in a cookbook’s /templates directory:
:sources: - http://<%= node['gem_file']['host'] %>:<%= node['gem_file']['port'] %>/
A recipe can be built that does the following:
template '/root/.gemrc' do source 'gemrc.erb' action :create notifies :run, 'ruby_block[refresh_gemrc]', :immediately end ruby_block 'refresh_gemrc' do action :nothing block do Gem.configuration = Gem::ConfigFile.new  end end gem_package 'di-ruby-lvm' do gem_binary '/opt/chef/embedded/bin/gem' action :install 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:
Ruby Types: TrueClass, FalseClass
Set to true to download a gem from the path specified by the source attribute (and not from RubyGems). Default value: false.
Ruby Type: String
An attribute for the gem_package provider that is used to specify a gems binary. By default, the same version of Ruby that is used by the chef-client will be installed.
Ruby Type: String
One (or more) additional options that are passed to the command.
Ruby Types: String, Array
The name of the package. Default value: the name of the resource block. (See “Syntax” section above for more information.)
Ruby Type: Chef Class
Optional. Use to explicitly specify a provider. (See “Providers” section below for more information.)
Ruby Type: String
Optional. The URL at which the gem package is located.
Ruby Types: String, Integer
The amount of time (in seconds) to wait before timing out.
Ruby Types: String, Array
The version of a package to be installed or upgraded.
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-client will determine the correct provider based on configuration data collected by Ohai at the start of the chef-client run. This configuration data is then mapped to a platform and an associated list of providers.
Generally, it’s best to let the chef-client choose the provider and this is (by far) the most common approach. However, in some cases specifying a provider may be desirable. There are two approaches:
This resource has the following providers:
|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 Chef uses resources in recipes, take a closer look at the cookbooks that Chef 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