chef 17.1.35 → 17.2.29

data/lib/chef/resource/openbsd_package.rb

@@ -31,6 +31,23 @@ class Chef
 
       description "Use the **openbsd_package** resource to manage packages for the OpenBSD platform."
       introduced "12.1"
+      examples <<~DOC
+        **Install a package**
+
+        ```ruby
+        openbsd_package 'name of package' do
+          action :install
+        end
+        ```
+
+        **Remove a package**
+
+        ```ruby
+        openbsd_package 'name of package' do
+          action :remove
+        end
+        ```
+      DOC
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",

data/lib/chef/resource/openssl_dhparam.rb

@@ -88,8 +88,7 @@ class Chef
         description: "The permission mode applied to all files created by the resource.",
         default: "0640"
 
-      action :create do
-        description "Create the dhparam file."
+      action :create, description: "Create the `dhparam.pem` file." do
         dhparam_content = nil
         unless dhparam_pem_valid?(new_resource.path)
           dhparam_content = gen_dhparam(new_resource.key_length, new_resource.generator).to_pem

data/lib/chef/resource/openssl_ec_private_key.rb

@@ -88,9 +88,7 @@ class Chef
         description: "Force creation of the key even if the same key already exists on the node.",
         default: false, desired_state: false
 
-      action :create do
-        description "Generate the ec private key"
-
+      action :create, description: "Generate the EC private key file." do
         unless new_resource.force || priv_key_file_valid?(new_resource.path, new_resource.key_pass)
           converge_by("Create an EC private key #{new_resource.path}") do
             log "Generating an #{new_resource.key_curve} "\

data/lib/chef/resource/openssl_ec_public_key.rb

@@ -74,9 +74,7 @@ class Chef
         description: "The permission mode applied to all files created by the resource.",
         default: "0640"
 
-      action :create do
-        description "Generate the ec public key from a private key"
-
+      action :create, description: "Generate the EC public key file from a private key." 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 EC 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_rsa_private_key.rb

@@ -87,9 +87,7 @@ class Chef
         description: "Force creation of the key even if the same key already exists on the node.",
         default: false, desired_state: false
 
-      action :create do
-        description "Create the RSA private key."
-
+      action :create, description: "Create the RSA private key file." do
         return if new_resource.force || priv_key_file_valid?(new_resource.path, new_resource.key_pass)
 
         converge_by("create #{new_resource.key_length} bit RSA key #{new_resource.path}") do

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/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/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

data/lib/chef/resource/swap_file.rb

@@ -63,9 +63,7 @@ class Chef
       property :swappiness, Integer,
         description: "The swappiness value to set on the system."
 
-      action :create do
-        description "Create a swapfile."
-
+      action :create, description: "Create a swapfile." do
         if swap_enabled?
           Chef::Log.debug("#{new_resource} already created - nothing to do")
         else
@@ -85,9 +83,7 @@ class Chef
         end
       end
 
-      action :remove do
-        description "Remove a swapfile and disable swap."
-
+      action :remove, description: "Remove a swapfile and disable swap." do
         swapoff if swap_enabled?
         remove_swapfile if ::File.exist?(new_resource.path)
       end

data/lib/chef/resource/sysctl.rb

@@ -131,7 +131,7 @@ class Chef
 
       end
 
-      action :apply, description: "Apply a sysctl value" do
+      action :apply, description: "Apply a sysctl value." 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 a sysctl value." 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/timezone.rb

@@ -119,7 +119,7 @@ class Chef
         end
       end
 
-      action :set, description: "Set the system timezone" do
+      action :set, description: "Set the system timezone." do
         # we have to check windows first since the value isn't case sensitive here
         if windows?
           unless current_windows_tz.casecmp?(new_resource.timezone)

data/lib/chef/resource/user_ulimit.rb

@@ -78,7 +78,7 @@ class Chef
                coerce: proc { |m| m.end_with?(".conf") ? m : m + ".conf" },
                default: lazy { |r| r.username == "*" ? "00_all_limits.conf" : "#{r.username}_limits.conf" }
 
-      action :create, description: "Create a ulimit configuration file" do
+      action :create, description: "Create a ulimit configuration file." do
         template "/etc/security/limits.d/#{new_resource.filename}" do
           source ::File.expand_path("support/ulimit.erb", __dir__)
           local true
@@ -106,7 +106,7 @@ class Chef
         end
       end
 
-      action :delete, description: "Delete an existing ulimit configuration file" do
+      action :delete, description: "Delete an existing ulimit configuration file." do
         file "/etc/security/limits.d/#{new_resource.filename}" do
           action :delete
         end