chef 17.3.48 → 17.4.25

data/lib/chef/provider/zypper_repository.rb

@@ -29,7 +29,7 @@ class Chef
 
       def load_current_resource; end
 
-      action :create do
+      action :create, description: "Add a new Zypper repository." do
         if new_resource.gpgautoimportkeys
           install_gpg_keys(new_resource.gpgkey)
         else
@@ -50,13 +50,13 @@ class Chef
         end
       end
 
-      action :delete do
+      action :delete, description: "Remove a Zypper repository." do
         execute "zypper --quiet --non-interactive removerepo #{escaped_repo_name}" do
           only_if "zypper --quiet lr #{escaped_repo_name}"
         end
       end
 
-      action :refresh do
+      action :refresh, description: "Refresh Zypper repository." do
         execute "zypper --quiet --non-interactive refresh --force #{escaped_repo_name}" do
           only_if "zypper --quiet lr #{escaped_repo_name}"
         end

data/lib/chef/provider.rb

@@ -57,10 +57,12 @@ class Chef
     #
     # @since 13.0
     # @param name [String, Symbol] Name of the action to define.
+    # @param description [String] description of the action
     # @param block [Proc] Body of the action.
     #
     # @return [void]
-    def self.action(name, &block)
+    def self.action(name, description: nil, &block)
+      action_descriptions[name.to_sym] = description unless description.nil?
       # We need the block directly in a method so that `return` works.
       define_method("compile_action_#{name}", &block)
       class_eval <<-EOM
@@ -70,6 +72,29 @@ class Chef
       EOM
     end
 
+    # Return the hash of action descriptions defined for
+    # the provider class.
+    #
+    # @return [Hash] hash of [Symbol] => [String] containing
+    # any provided action descriptions.
+    def self.action_descriptions
+      @action_descriptions ||= {}
+    end
+
+    # Retrieve the description for a provider's action, if
+    # any description has been included in the definition.
+    #
+    # @param action [Symbol,String] the action name
+    # @return [String] the description of the action provided, or nil if no description
+    # was defined
+    def self.action_description(action)
+      description = action_descriptions[action.to_sym]
+      if description.nil? && superclass.respond_to?(:action_description)
+        description = superclass.action_description(action)
+      end
+      description
+    end
+
     # Deprecation stub for the old use_inline_resources mode.
     #
     # @return [void]

data/lib/chef/provider_resolver.rb

@@ -57,10 +57,16 @@ class Chef
     end
 
     def resolve
-      maybe_explicit_provider(resource) ||
+      resolved = maybe_explicit_provider(resource) ||
         maybe_custom_resource(resource) ||
-        maybe_dynamic_provider_resolution(resource, action) ||
+        maybe_dynamic_provider_resolution(resource, action)
+
+      if resolved.nil?
+        raise(Chef::Exceptions::ProviderNotFound, "Cannot find a provider for #{resource}") if node.nil?
+
         raise(Chef::Exceptions::ProviderNotFound, "Cannot find a provider for #{resource} on #{node["platform"]} version #{node["platform_version"]}")
+      end
+      resolved
     end
 
     # Does NOT call provides? on the resource (it is assumed this is being

data/lib/chef/resource/homebrew_cask.rb

@@ -34,7 +34,7 @@ class Chef
 
       property :cask_name, String,
         description: "An optional property to set the cask name if it differs from the resource block's name.",
-        regex: %r{^[\w/-]+$},
+        regex: %r{^[\w/\-@]+$},
         validation_message: "The provided Homebrew cask name is not valid. Cask names can contain alphanumeric characters, _, -, or / only!",
         name_property: true
 

data/lib/chef/resource/inspec_waiver_file_entry.rb

@@ -84,13 +84,13 @@ class Chef
         }
 
       property :run_test, [true, false],
-        description: "If present and true, the control will run and be reported, but failures in it won’t make the overall run fail. If absent or false, the control will not be run."
+        description: "If present and `true`, the control will run and be reported, but failures in it won’t make the overall run fail. If absent or `false`, the control will not be run."
 
       property :justification, String,
         description: "Can be any text you want and might include a reason for the waiver as well as who signed off on the waiver."
 
       property :backup, [false, Integer],
-        description: "The number of backups to be kept in /var/chef/backup (for UNIX- and Linux-based platforms) or C:/chef/backup (for the Microsoft Windows platform). Set to false to prevent backups from being kept.",
+        description: "The number of backups to be kept in `/var/chef/backup` (for UNIX- and Linux-based platforms) or `C:/chef/backup` (for the Microsoft Windows platform). Set to `false` to prevent backups from being kept.",
         default: false
 
       action :add do

data/lib/chef/resource/launchd.rb

@@ -36,7 +36,7 @@ class Chef
 
       property :backup, [Integer, FalseClass],
         desired_state: false,
-        description: "The number of backups to be kept in /var/chef/backup. Set to false to prevent backups from being kept."
+        description: "The number of backups to be kept in `/var/chef/backup`. Set to `false` to prevent backups from being kept."
 
       property :cookbook, String,
         desired_state: false,
@@ -197,10 +197,10 @@ class Chef
         description: "The intended purpose of the job: `Adaptive`, `Background`, `Interactive`, or `Standard`."
 
       property :program, String,
-        description: "The first argument of execvp, typically the file name associated with the file to be executed. This value must be specified if program_arguments is not specified, and vice-versa."
+        description: "The first argument of `execvp`, typically the file name associated with the file to be executed. This value must be specified if `program_arguments` is not specified, and vice-versa."
 
       property :program_arguments, Array,
-        description: "The second argument of execvp. If program is not specified, this property must be specified and will be handled as if it were the first argument."
+        description: "The second argument of `execvp`. If program is not specified, this property must be specified and will be handled as if it were the first argument."
 
       property :queue_directories, Array,
         description: "An array of non-empty directories which, if any are modified, will cause a job to be started."

data/lib/chef/resource/remote_file.rb

@@ -85,7 +85,7 @@ class Chef
       end
 
       property :use_etag, [ TrueClass, FalseClass ], default: true,
-        description: "Enable ETag headers. Set to false to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
+        description: "Enable ETag headers. Set to `false` to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
 
       alias :use_etags :use_etag
 

data/lib/chef/resource/rhsm_subscription.rb

@@ -32,11 +32,11 @@ class Chef
         name_property: true
 
       action :attach, description: "Attach the node to a subscription pool." do
-        execute "Attach subscription pool #{new_resource.pool_id}" do
-          command "subscription-manager attach --pool=#{new_resource.pool_id}"
-          default_env true
-          action :run
-          not_if { subscription_attached?(new_resource.pool_id) }
+        unless subscription_attached?(new_resource.pool_id)
+          converge_by("attach subscription pool #{new_resource.pool_id}") do
+            shell_out!("subscription-manager attach --pool=#{new_resource.pool_id}")
+            build_resource(:package, "rhsm_subscription-#{new_resource.pool_id}-flush_cache").run_action(:flush_cache)
+          end
         end
       end
 

data/lib/chef/resource/ruby_block.rb

@@ -29,6 +29,106 @@ class Chef
       provides :ruby_block, target_mode: true
 
       description "Use the **ruby_block** resource to execute Ruby code during a #{ChefUtils::Dist::Infra::PRODUCT} 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."
+      examples <<~'DOC'
+        **Reload Chef Infra Client configuration data**
+
+        ```ruby
+        ruby_block 'reload_client_config' do
+          block do
+            Chef::Config.from_file('/etc/chef/client.rb')
+          end
+          action :run
+        end
+        ```
+
+        **Run a block on a particular platform**
+
+        The following example shows how an if statement can be used with the `windows?` method in the Chef Infra Language to run code specific to Microsoft Windows. The code is defined using the ruby_block resource:
+
+        ```ruby
+        if windows?
+          ruby_block 'copy libmysql.dll into ruby path' do
+            block do
+              require 'fileutils'
+              FileUtils.cp "#{node['mysql']['client']['lib_dir']}\\libmysql.dll",
+                node['mysql']['client']['ruby_dir']
+            end
+            not_if { ::File.exist?("#{node['mysql']['client']['ruby_dir']}\\libmysql.dll") }
+          end
+        end
+        ```
+
+        **Stash a file in a data bag**
+
+        The following example shows how to use the ruby_block resource to stash a BitTorrent file in a data bag so that it can be distributed to nodes in the organization.
+
+        ```ruby
+        ruby_block 'share the torrent file' do
+          block do
+            f = File.open(node['bittorrent']['torrent'],'rb')
+            #read the .torrent file and base64 encode it
+            enc = Base64.encode64(f.read)
+            data = {
+              'id'=>bittorrent_item_id(node['bittorrent']['file']),
+              'seed'=>node.ipaddress,
+              'torrent'=>enc
+            }
+            item = Chef::DataBagItem.new
+            item.data_bag('bittorrent')
+            item.raw_data = data
+            item.save
+          end
+          action :nothing
+          subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately
+        end
+        ```
+
+        **Update the /etc/hosts file**
+
+        The following example shows how the ruby_block resource can be used to update the /etc/hosts file:
+
+        ```ruby
+        ruby_block 'edit etc hosts' do
+          block do
+            rc = Chef::Util::FileEdit.new('/etc/hosts')
+            rc.search_file_replace_line(/^127\.0\.0\.1 localhost$/,
+              '127.0.0.1 #{new_fqdn} #{new_hostname} localhost')
+            rc.write_file
+          end
+        end
+        ```
+
+        **Set environment variables**
+
+        The following example shows how to use variables within a Ruby block to set environment variables using rbenv.
+
+        ```ruby
+        node.override[:rbenv][:root] = rbenv_root
+        node.override[:ruby_build][:bin_path] = rbenv_binary_path
+
+        ruby_block 'initialize' do
+          block do
+            ENV['RBENV_ROOT'] = node[:rbenv][:root]
+            ENV['PATH'] = "#{node[:rbenv][:root]}/bin:#{node[:ruby_build][:bin_path]}:#{ENV['PATH']}"
+          end
+        end
+        ```
+
+        **Call methods in a gem**
+
+        The following example shows how to call methods in gems not shipped in Chef Infra Client
+
+        ```ruby
+        chef_gem 'mongodb'
+
+        ruby_block 'config_replicaset' do
+          block do
+            MongoDB.configure_replicaset(node, replicaset_name, rs_nodes)
+          end
+          action :run
+        end
+        ```
+      DOC
 
       default_action :run
       allowed_actions :create, :run

data/lib/chef/resource/scm/subversion.rb

@@ -28,7 +28,7 @@ class Chef
 
       provides :subversion
 
-      description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository."
+      description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository. Warning: The subversion resource has known bugs and may not work as expected. For more information see Chef GitHub issues, particularly [#4050](https://github.com/chef/chef/issues/4050) and [#4257](https://github.com/chef/chef/issues/4257)."
       examples <<~DOC
       **Get the latest version of an application**
 

data/lib/chef/resource/sysctl.rb

@@ -131,7 +131,7 @@ class Chef
 
       end
 
-      action :apply, description: "Apply a sysctl value." do
+      action :apply, description: "Set the kernel parameter and update the `sysctl` settings." do
         converge_if_changed do
           # set it temporarily
           set_sysctl_param(new_resource.key, new_resource.value)
@@ -150,7 +150,7 @@ class Chef
         end
       end
 
-      action :remove, description: "Remove a sysctl value." do
+      action :remove, description: "Remove the kernel parameter and update the `sysctl` settings." do
         # only converge the resource if the file actually exists to delete
         if ::File.exist?("#{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf")
           converge_by "removing sysctl config at #{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf" do

data/lib/chef/resource/systemd_unit.rb

@@ -34,7 +34,7 @@ class Chef
 
       ```ruby
       systemd_unit 'etcd.service' do
-        content(Unit: {
+        content({ Unit: {
                   Description: 'Etcd',
                   Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'],
                   After: 'network.target',
@@ -46,7 +46,7 @@ class Chef
                 },
                 Install: {
                   WantedBy: 'multi-user.target',
-                })
+                } })
         action [:create, :enable]
       end
       ```
@@ -113,7 +113,7 @@ class Chef
         when Hash
           IniParse.gen do |doc|
             content.each_pair do |sect, opts|
-              doc.section(sect) do |section|
+              doc.section(sect, { option_sep: "=" }) do |section|
                 opts.each_pair do |opt, val|
                   [val].flatten.each do |v|
                     section.option(opt, v)

data/lib/chef/resource/yum_package.rb

@@ -27,11 +27,7 @@ class Chef
       provides :yum_package
       provides :package, platform_family: "fedora_derived"
 
-      description "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."
+      description "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. Note: Support for using file names to install packages (as in `yum_package '/bin/sh'`) is not available because the volume of data required to parse for this is excessive."
       examples <<~DOC
         **Install an exact version**:
 

data/lib/chef/resource.rb

@@ -1063,7 +1063,8 @@ class Chef
     # action for the resource.
     #
     # @param name [Symbol] The action name to define.
-    # @param description [String] optional description for the action
+    # @param description [String] optional description for the action. Used for
+    #   documentation generation.
     # @param recipe_block The recipe to run when the action is taken. This block
     #   takes no parameters, and will be evaluated in a new context containing:
     #
@@ -1076,11 +1077,8 @@ class Chef
     def self.action(action, description: nil, &recipe_block)
       action = action.to_sym
       declare_action_class
-      action_class.action(action, &recipe_block)
+      action_class.action(action, description: description, &recipe_block)
       self.allowed_actions += [ action ]
-      # Accept any non-nil description, which will correctly override
-      # any specific inherited description.
-      action_descriptions[action] = description unless description.nil?
       default_action action if Array(default_action) == [:nothing]
     end
 
@@ -1090,18 +1088,15 @@ class Chef
     # @param action [Symbol,String] the action name
     # @return the description of the action provided, or nil if no description
     # was defined
-    def self.action_description(action)
-      action_descriptions[action.to_sym]
-    end
-
-    # @api private
-    #
-    # @return existing action description hash, or newly-initialized
-    # hash containing action descriptions inherited from parent Resource,
-    # if any.
-    def self.action_descriptions
-      @action_descriptions ||=
-        superclass.respond_to?(:action_descriptions) ? superclass.action_descriptions.dup : { nothing: nil }
+    def action_description(action)
+      provider_for_action(action).class.action_description(action)
+    rescue Chef::Exceptions::ProviderNotFound
+      # If a provider can't be found, there can be no description defined on the provider.
+      nil
+    rescue NameError => e
+      # This can happen when attempting to load a provider in a platform-specific
+      # environment where we have not required the necessary files yet
+      raise unless e.message =~ /uninitialized constant/
     end
 
     # Define a method to load up this resource's properties with the current
@@ -1188,9 +1183,10 @@ class Chef
         begin
           is_custom_resource!
           base_provider =
-            if superclass.custom_resource?
+            if superclass.custom_resource? || superclass != Chef::Resource
               superclass.action_class
             else
+
               ActionClass
             end
 

data/lib/chef/resource_inspector.rb

@@ -23,6 +23,11 @@ require_relative "node"
 require_relative "resources"
 require_relative "json_compat"
 
+# We need to require providers  so that we can resolve
+# action documentation that may have been defined on the providers
+# instead of the resources.
+require_relative "providers"
+
 class Chef
   module ResourceInspector
     def self.get_default(default)
@@ -39,11 +44,10 @@ class Chef
     def self.extract_resource(resource, complete = false)
       data = {}
       data[:description] = resource.description
-      # data[:deprecated] = resource.deprecated || false
       data[:default_action] = resource.default_action
       data[:actions] = {}
       resource.allowed_actions.each do |action|
-        data[:actions][action] = resource.action_description(action)
+        data[:actions][action] = resource.new(resource.to_s, nil).action_description(action)
       end
 
       data[:examples] = resource.examples

data/lib/chef/secret_fetcher/aws_secrets_manager.rb

@@ -17,6 +17,7 @@
 #
 
 require_relative "base"
+require "aws-sdk-core"
 require "aws-sdk-secretsmanager"
 
 class Chef
@@ -26,19 +27,30 @@ class Chef
   # It is possible to pass options that configure it to use alternative credentials.
   # This implementation supports fetching with version.
   #
-  # NOTE: This does not yet support automatic retries, which the AWS client does by default.
+  # @note ':region' is required configuration.  If it is not explicitly provided,
+  # and it is not available via global AWS config, we will pull it from node ohai data by default.
+  # If this isn't correct, you will need to explicitly override it.
+  # If it is not available via ohai data either (such as if you have the AWS plugin disabled)
+  # then the converge will fail with an error.
+  #
+  # @note: This does not yet support automatic retries, which the AWS client does by default.
   #
   # For configuration options see https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SecretsManager/Client.html#initialize-instance_method
   #
-  # Note that ~/.aws default and environment-based configurations are supported by default in the
-  # ruby SDK.
   #
   # Usage Example:
   #
-  # fetcher = SecretFetcher.for_service(:aws_secrets_manager, { region: "us-east-1" })
+  # fetcher = SecretFetcher.for_service(:aws_secrets_manager)
   # fetcher.fetch("secretkey1", "v1")
   class SecretFetcher
     class AWSSecretsManager < Base
+      def validate!
+        config[:region] = config[:region] || Aws.config[:region] || run_context.node.dig("ec2", "region")
+        if config[:region].nil?
+          raise Chef::Exceptions::Secret::ConfigurationInvalid.new("Missing required config for AWS secret fetcher: :region")
+        end
+      end
+
       # @param identifier [String] the secret_id
       # @param version [String] the secret version. Not usd at this time
       # @return Aws::SecretsManager::Types::GetSecretValueResponse