chef 17.1.35-universal-mingw32 → 17.4.38-universal-mingw32

data/lib/chef/resource/openssl_rsa_public_key.rb

@@ -75,9 +75,7 @@ class Chef
         description: "The permission mode applied to all files created by the resource.",
         default: "0640"
 
-      action :create do
-        description "Create the RSA public key."
-
+      action :create, description: "Create the RSA public key file." do
         raise ArgumentError, "You cannot specify both 'private_key_path' and 'private_key_content' properties at the same time." if new_resource.private_key_path && new_resource.private_key_content
         raise ArgumentError, "You must specify the private key with either 'private_key_path' or 'private_key_content' properties." unless new_resource.private_key_path || new_resource.private_key_content
         raise "#{new_resource.private_key_path} not a valid private RSA key or password is invalid" unless priv_key_file_valid?((new_resource.private_key_path || new_resource.private_key_content), new_resource.private_key_pass)

data/lib/chef/resource/openssl_x509_certificate.rb

@@ -151,15 +151,12 @@ class Chef
         description: "The number of days before the expiry. The certificate will be automatically renewed when the value is reached.",
         introduced: "15.7"
 
-      action :create do
-        description "Generate a certificate"
-
+      action :create, description: "Generate a certificate file." do
         file new_resource.path do
           action :create_if_missing
           owner new_resource.owner unless new_resource.owner.nil?
           group new_resource.group unless new_resource.group.nil?
           mode new_resource.mode unless new_resource.mode.nil?
-          sensitive true
           content cert.to_pem
         end
 

data/lib/chef/resource/openssl_x509_crl.rb

@@ -90,9 +90,7 @@ class Chef
       property :mode, [Integer, String],
         description: "The permission mode of the CRL file."
 
-      action :create do
-        description "Create the CRL file."
-
+      action :create, description: "Create the certificate revocation list (CRL) file." do
         file new_resource.path do
           owner new_resource.owner unless new_resource.owner.nil?
           group new_resource.group unless new_resource.group.nil?

data/lib/chef/resource/openssl_x509_request.rb

@@ -119,9 +119,7 @@ class Chef
         equal_to: %w{secp384r1 secp521r1 prime256v1}, default: "prime256v1",
         description: "The desired curve of the generated key (if key_type is equal to `ec`). Run `openssl ecparam -list_curves` to see available options."
 
-      action :create do
-        description "Generate a certificate request."
-
+      action :create, description: "Generate a certificate request file." do
         unless ::File.exist? new_resource.path
           converge_by("Create CSR #{@new_resource}") do
             file new_resource.path do

data/lib/chef/resource/osx_profile.rb

@@ -51,7 +51,7 @@ class Chef
         'PayloadOrganization' => 'Chef',
         'PayloadVersion' => 1,
         'PayloadDisplayName' => 'Screensaver Settings',
-        'PayloadContent'=> [
+        'PayloadContent' => [
           {
             'PayloadType' => 'com.apple.ManagedClient.preferences',
             'PayloadVersion' => 1,
@@ -172,7 +172,7 @@ class Chef
         end
       end
 
-      action :install do
+      action :install, description: "Install the specified configuration profile." do
         unless profile_installed?
           converge_by("install profile #{new_profile_identifier}") do
             profile_path = write_profile_to_disk
@@ -182,7 +182,7 @@ class Chef
         end
       end
 
-      action :remove do
+      action :remove, description: "Remove the specified configuration profile." do
         # Clean up profile after removing it
         if profile_installed?
           converge_by("remove profile #{new_profile_identifier}") do

data/lib/chef/resource/plist.rb

@@ -81,7 +81,7 @@ class Chef
         group file_group_cmd.stdout.chomp
       end
 
-      action :set do
+      action :set, description: "Set a value in a plist file." do
         converge_if_changed :path do
           converge_by "create new plist: '#{new_resource.path}'" do
             file new_resource.path do

data/lib/chef/resource/powershell_package_source.rb

@@ -70,8 +70,7 @@ class Chef
         script_publish_location status["script_publish_location"]
       end
 
-      action :register do
-        description "Registers and updates the powershell package source."
+      action :register, description: "Registers and updates the PowerShell package source." do
         # TODO: Ensure package provider is installed?
         if psrepository_cmdlet_appropriate?
           if package_source_exists?
@@ -104,8 +103,7 @@ class Chef
         end
       end
 
-      action :unregister do
-        description "Unregisters the powershell package source."
+      action :unregister, description: "Unregisters the PowerShell package source." do
         if package_source_exists?
           unregister_cmd = "Get-PackageSource -Name '#{new_resource.source_name}' | Unregister-PackageSource"
           converge_by("unregister source: #{new_resource.source_name}") do

data/lib/chef/resource/reboot.rb

@@ -33,6 +33,41 @@ class Chef
                   " immediate notifications. Delayed notifications produce unintuitive and"\
                   " probably undesired results."
       introduced "12.0"
+      examples <<~DOC
+        **Reboot a node immediately**
+
+        ```ruby
+        reboot 'now' do
+          action :nothing
+          reason 'Cannot continue Chef run without a reboot.'
+          delay_mins 2
+        end
+
+        execute 'foo' do
+          command '...'
+          notifies :reboot_now, 'reboot[now]', :immediately
+        end
+        ```
+
+        **Reboot a node at the end of a Chef Infra Client run**
+
+        ```ruby
+        reboot 'app_requires_reboot' do
+          action :request_reboot
+          reason 'Need to reboot when the run completes successfully.'
+          delay_mins 5
+        end
+        ```
+
+        **Cancel a reboot**
+
+        ```ruby
+        reboot 'cancel_reboot_request' do
+          action :cancel
+          reason 'Cancel a previous end-of-run reboot request.'
+        end
+        ```
+      DOC
 
       property :reason, String,
         description: "A string that describes the reboot action.",
@@ -42,18 +77,14 @@ class Chef
         description: "The amount of time (in minutes) to delay a reboot request.",
         default: 0
 
-      action :request_reboot do
-        description "Reboot a node at the end of a chef-client run."
-
+      action :request_reboot, description: "Reboot a node at the end of a #{ChefUtils::Dist::Infra::PRODUCT} run." do
         converge_by("request a system reboot to occur if the run succeeds") do
           logger.warn "Reboot requested:'#{new_resource.name}'"
           request_reboot
         end
       end
 
-      action :reboot_now do
-        description "Reboot a node so that the chef-client may continue the installation process."
-
+      action :reboot_now, description: "Reboot a node so that the #{ChefUtils::Dist::Infra::PRODUCT} may continue the installation process." do
         converge_by("rebooting the system immediately") do
           logger.warn "Rebooting system immediately, requested by '#{new_resource.name}'"
           request_reboot
@@ -61,9 +92,7 @@ class Chef
         end
       end
 
-      action :cancel do
-        description "Cancel a pending reboot request."
-
+      action :cancel, description: "Cancel a pending reboot request." do
         converge_by("cancel any existing end-of-run reboot request") do
           logger.warn "Reboot canceled: '#{new_resource.name}'"
           node.run_context.cancel_reboot

data/lib/chef/resource/remote_directory.rb

@@ -71,7 +71,7 @@ class Chef
         desired_state: false
 
       property :files_group, [String, Integer],
-        description: "Configure group permissions for files. A string or ID that identifies the group owner by group name, including fully qualified group names such as domain\\group or group@domain. If this value is not specified, existing groups remain unchanged and new group assignments use the default POSIX group (if available).",
+        description: "Configure group permissions for files. A string or ID that identifies the group owner by group name, including fully qualified group names such as `domain\\group` or `group@domain`. If this value is not specified, existing groups remain unchanged and new group assignments use the default POSIX group (if available).",
         regex: Chef::Config[:group_valid_regex]
 
       property :files_mode, [String, Integer, nil],
@@ -80,7 +80,7 @@ class Chef
         regex: /^\d{3,4}$/, default: lazy { 0644 unless Chef::Platform.windows? }
 
       property :files_owner, [String, Integer],
-        description: "Configure owner permissions for files. A string or ID that identifies the group owner by user name, including fully qualified user names such as domain\\user or user@domain. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).",
+        description: "Configure owner permissions for files. A string or ID that identifies the group owner by user name, including fully qualified user names such as `domain\\user` or `user@domain`. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).",
         regex: Chef::Config[:user_valid_regex]
     end
   end

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_errata.rb

@@ -46,8 +46,6 @@ class Chef
         name_property: true
 
       action :install, description: "Install a package for a specific errata ID." do
-        description "Installs a package for a specific errata ID."
-
         execute "Install errata packages for #{new_resource.errata_id}" do
           command "#{package_manager_command} update --advisory #{new_resource.errata_id} -y"
           default_env true

data/lib/chef/resource/rhsm_errata_level.rb

@@ -42,11 +42,7 @@ class Chef
         name_property: true
 
       action :install, description: "Install all packages of the specified errata level." do
-        description "Install all packages of the specified errata level."
-
-        if rhel6?
-          yum_package "yum-plugin-security"
-        end
+        yum_package "yum-plugin-security" if rhel6?
 
         execute "Install any #{new_resource.errata_level} errata" do
           command "#{package_manager_command} update --sec-severity=#{new_resource.errata_level.capitalize} -y"

data/lib/chef/resource/rhsm_repo.rb

@@ -26,6 +26,21 @@ class Chef
 
       description "Use the **rhsm_repo** resource to enable or disable Red Hat Subscription Manager repositories that are made available via attached subscriptions."
       introduced "14.0"
+      examples <<~DOC
+        **Enable an RHSM repository**
+
+        ```ruby
+        rhsm_repo 'rhel-7-server-extras-rpms'
+        ```
+
+        **Disable an RHSM repository**
+
+        ```ruby
+        rhsm_repo 'rhel-7-server-extras-rpms' do
+          action :disable
+        end
+        ```
+      DOC
 
       property :repo_name, String,
         description: "An optional property for specifying the repository name if it differs from the resource block's name.",

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/ssh_known_hosts_entry.rb

@@ -75,7 +75,8 @@ class Chef
 
       property :group, [String, Integer],
         description: "The file group for the ssh_known_hosts file.",
-        default: lazy { node["root_group"] }
+        default: lazy { node["root_group"] },
+        default_description: "The root user's group depending on platform."
 
       property :hash_entries, [TrueClass, FalseClass],
         description: "Hash the hostname and addresses in the ssh_known_hosts file for privacy.",
@@ -85,9 +86,7 @@ class Chef
         description: "The location of the ssh known hosts file. Change this to set a known host file for a particular user.",
         default: "/etc/ssh/ssh_known_hosts"
 
-      action :create do
-        description "Create an entry in the ssh_known_hosts file."
-
+      action :create, description: "Create an entry in the ssh_known_hosts file." do
         key =
           if new_resource.key
             hoststr = (new_resource.port != 22) ? "[#{new_resource.host}]:#{new_resource.port}" : new_resource.host
@@ -129,9 +128,7 @@ class Chef
       end
 
       # all this does is send an immediate run_action(:create) to the template resource
-      action :flush do
-        description "Immediately flush the entries to the config file. Without this the actual writing of the file is delayed in the #{ChefUtils::Dist::Infra::PRODUCT} run so all entries can be accumulated before writing the file out."
-
+      action :flush, description: "Immediately flush the entries to the config file. Without this the actual writing of the file is delayed in the #{ChefUtils::Dist::Infra::PRODUCT} run so all entries can be accumulated before writing the file out." do
         with_run_context :root do
           # if you haven't ever called ssh_known_hosts_entry before you're definitely doing it wrong so we blow up hard.
           find_resource!(:template, "update ssh known hosts file #{new_resource.file_location}").run_action(:create)

data/lib/chef/resource/sudo.rb

@@ -170,9 +170,7 @@ class Chef
         end
       end
 
-      action :create do
-        description "Create a single sudoers config in the sudoers.d directory"
-
+      action :create, description: "Create a single sudoers configuration file in the `sudoers.d` directory." do
         validate_properties
 
         if docker? # don't even put this into resource collection unless we're in docker
@@ -230,9 +228,7 @@ class Chef
       end
 
       # Removes a user from the sudoers group
-      action :delete do
-        description "Remove a sudoers config from the sudoers.d directory"
-
+      action :delete, description: "Remove a sudoers configuration file from the `sudoers.d` directory." do
         file "#{new_resource.config_prefix}/sudoers.d/#{new_resource.filename}" do
           action :delete
         end