diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/chef/resource/chef_gem.rb | 78 | ||||
| -rw-r--r-- | lib/chef/resource/gem_package.rb | 37 |
2 files changed, 92 insertions, 23 deletions
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb index 664144619c..b44f9e1771 100644 --- a/lib/chef/resource/chef_gem.rb +++ b/lib/chef/resource/chef_gem.rb @@ -22,26 +22,59 @@ require_relative "../dist" class Chef class Resource - # Use the chef_gem resource to install a gem only for the instance of Ruby that is dedicated to the chef-client. - # When a gem 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 - - require_relative "gem_package" - require_relative "../dist" - class ChefGem < Chef::Resource::Package::GemPackage unified_mode true provides :chef_gem + description <<~DESC + Use the **chef_gem** resource to install a gem only for the instance of Ruby that is dedicated to the #{Chef::Dist::CLIENT}. + When a gem 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::Dist::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. + + Warning: The **chef_gem** and **gem_package** resources are both used to install Ruby gems. For any machine on which #{Chef::Dist::PRODUCT} 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 #{Chef::Dist::PRODUCT}. + Use the **chef_gem** resource to install gems into the instance of Ruby that is dedicated to #{Chef::Dist::PRODUCT}. + Use the **gem_package** resource to install all other gems (i.e. install gems system-wide). + DESC + + examples <<~EXAMPLES + **Compile time vs. converge time installation of gems** + + To install a gem while #{Chef::Dist::PRODUCT} is configuring the node (the converge phase), set the `compile_time` property to `false`: + ```ruby + chef_gem 'right_aws' do + compile_time false + action :install + end + ``` + + To install a gem while the resource collection is being built (the compile phase), set the `compile_time` property to `true`: + ```ruby + chef_gem 'right_aws' do + compile_time true + action :install + end + ``` + + Install MySQL for Chef + ```ruby + apt_update + + build_essential 'install compilation tools' do + compile_time true + end + + chef_gem 'mysql' + ``` + EXAMPLES + property :package_name, String, description: "An optional property to set the package name if it differs from the resource block's name.", identity: true @@ -49,11 +82,14 @@ class Chef property :version, String, description: "The version of a package to be installed or upgraded." - property :gem_binary, default: "#{RbConfig::CONFIG["bindir"]}/gem", default_description: "The `gem` binary included with #{Chef::Dist::PRODUCT}.", - description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be installed.", - callbacks: { - "The chef_gem resource is restricted to the current gem environment, use gem_package to install to other environments." => proc { |v| v == "#{RbConfig::CONFIG["bindir"]}/gem" }, - } + property :gem_binary, String, + default: "#{RbConfig::CONFIG["bindir"]}/gem", + default_description: "The `gem` binary included with #{Chef::Dist::PRODUCT}.", + description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be used.", + callbacks: { + "The `chef_gem` resource is restricted to the current gem environment, use `gem_package` to install to other environments." => + proc { |v| v == "#{RbConfig::CONFIG["bindir"]}/gem" }, + } end end end diff --git a/lib/chef/resource/gem_package.rb b/lib/chef/resource/gem_package.rb index def92bd34d..05f8611233 100644 --- a/lib/chef/resource/gem_package.rb +++ b/lib/chef/resource/gem_package.rb @@ -25,7 +25,40 @@ class Chef unified_mode true provides :gem_package - description "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." + description <<~DESC + Use the **gem_package** resource to manage gem packages that are only included in recipes. + When a gem is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources. + + Note: The **gem_package** resource must be specified as `gem_package` and cannot be shortened to `package` in a recipe. + + Warning: The **chef_gem** and **gem_package** resources are both used to install Ruby gems. For any machine on which #{Chef::Dist::PRODUCT} 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 #{Chef::Dist::PRODUCT}. + Use the **chef_gem** resource to install gems into the instance of Ruby that is dedicated to #{Chef::Dist::PRODUCT}. + Use the **gem_package** resource to install all other gems (i.e. install gems system-wide). + DESC + + examples <<~EXAMPLES + The following examples demonstrate various approaches for using the **gem_package** resource in recipes: + + **Install a gem file from the local file system** + + ```ruby + gem_package 'right_aws' do + source '/tmp/right_aws-1.11.0.gem' + action :install + end + ``` + + **Use the `ignore_failure` common attribute** + + ```ruby + gem_package 'syntax' do + action :install + ignore_failure true + end + ``` + EXAMPLES property :package_name, String, description: "An optional property to set the package name if it differs from the resource block's name.", @@ -53,7 +86,7 @@ class Chef default: lazy { Chef::Config[:clear_gem_sources] }, desired_state: false property :gem_binary, String, desired_state: false, - description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be installed." + description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be used." property :include_default_source, [ TrueClass, FalseClass, nil ], description: "Set to `false` to not include `Chef::Config[:rubygems_url]` in the sources.", |