chef 16.11.7 → 17.2.29

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

@@ -64,24 +64,24 @@ class Chef
                              "utf-8" => "xml1",
                              "binary" => "binary1" }.freeze
 
-      load_current_value do |desired|
-        current_value_does_not_exist! unless ::File.exist? desired.path
-        entry desired.entry if entry_in_plist? desired.entry, desired.path
+      load_current_value do |new_resource|
+        current_value_does_not_exist! unless ::File.exist? new_resource.path
+        entry new_resource.entry if entry_in_plist? new_resource.entry, new_resource.path
 
-        setting = setting_from_plist desired.entry, desired.path
+        setting = setting_from_plist new_resource.entry, new_resource.path
         value convert_to_data_type_from_string(setting[:key_type], setting[:key_value])
 
-        file_type_cmd = shell_out "/usr/bin/file", "--brief", "--mime-encoding", "--preserve-date", desired.path
+        file_type_cmd = shell_out "/usr/bin/file", "--brief", "--mime-encoding", "--preserve-date", new_resource.path
         encoding file_type_cmd.stdout.chomp
 
-        file_owner_cmd = shell_out("/usr/bin/stat", "-f", "%Su", desired.path)
+        file_owner_cmd = shell_out("/usr/bin/stat", "-f", "%Su", new_resource.path)
         owner file_owner_cmd.stdout.chomp
 
-        file_group_cmd = shell_out("/usr/bin/stat", "-f", "%Sg", desired.path)
+        file_group_cmd = shell_out("/usr/bin/stat", "-f", "%Sg", new_resource.path)
         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/powershell_script.rb

@@ -27,7 +27,7 @@ class Chef
       provides :powershell_script, os: "windows"
 
       description <<~DESC
-        Use the **powershell_script** resource to execute a script using the Windows PowerShell interpreter, much like how the script and script-based resources **bash**, **csh**, **perl**, **python**, and **ruby** are used. The **powershell_script** resource is specific to the Microsoft Windows platform, but may use both the the Windows PowerShell interpreter or the PowerShell Core (pwsh) interpreter as of Chef Infra Client 16.6 and later.
+        Use the **powershell_script** resource to execute a script using the Windows PowerShell interpreter, much like how the script and script-based resources **bash**, **csh**, **perl**, **python**, and **ruby** are used. The **powershell_script** resource is specific to the Microsoft Windows platform, but may use both the Windows PowerShell interpreter or the PowerShell Core (pwsh) interpreter as of Chef Infra Client 16.6 and later.
 
         The **powershell_script** resource creates and executes a temporary file rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use `not_if` and `only_if` conditionals to guard this resource for idempotence.
       DESC

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

@@ -95,7 +95,7 @@ class Chef
       property :ftp_active_mode, [ TrueClass, FalseClass ], default: false,
         description: "Whether #{ChefUtils::Dist::Infra::PRODUCT} uses active or passive FTP. Set to `true` to use active FTP."
 
-      property :headers, Hash, default: lazy { {} },
+      property :headers, Hash, default: {},
         description: "A Hash of custom HTTP headers."
 
       property :show_progress, [ TrueClass, FalseClass ], default: false
@@ -142,13 +142,13 @@ class Chef
         end
 
         # if domain is provided in both username and domain
-        if specified_user && ((specified_user.include? '\\') || (specified_user.include? "@")) && specified_domain
+        if specified_user && ((specified_user.include? "\\") || (specified_user.include? "@")) && specified_domain
           raise ArgumentError, "The domain is provided twice. Username: `#{specified_user}`, Domain: `#{specified_domain}`. Please specify domain only once."
         end
 
         if ! specified_user.nil? && specified_domain.nil?
           # Splitting username of format: Domain\Username
-          domain_and_user = user.split('\\')
+          domain_and_user = user.split("\\")
 
           if domain_and_user.length == 2
             domain = domain_and_user[0]

data/lib/chef/resource/rhsm_errata.rb

@@ -25,14 +25,27 @@ class Chef
 
       description "Use the **rhsm_errata** resource to install packages associated with a given Red Hat Subscription Manager Errata ID. This is helpful if packages to mitigate a single vulnerability must be installed on your hosts."
       introduced "14.0"
+      examples <<~DOC
+        **Install a package from an Errata ID**
+
+        ```ruby
+        rhsm_errata 'RHSA:2018-1234'
+        ```
+
+        **Specify an Errata ID that differs from the resource name**
+
+        ```ruby
+        rhsm_errata 'errata-install'
+          errata_id 'RHSA:2018-1234'
+        end
+        ```
+      DOC
 
       property :errata_id, String,
         description: "An optional property for specifying the errata ID if it differs from the resource block's name.",
         name_property: true
 
-      action :install do
-        description "Installs a package for a specific errata ID."
-
+      action :install, description: "Install a package for a specific errata ID." do
         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

@@ -25,6 +25,15 @@ class Chef
 
       description "Use the **rhsm_errata_level** resource to install all packages of a specified errata level from the Red Hat Subscription Manager. For example, you can ensure that all packages associated with errata marked at a 'Critical' security level are installed."
       introduced "14.0"
+      examples <<~DOC
+        **Specify an errata level that differs from the resource name**
+
+        ```ruby
+        rhsm_errata_level 'example_install_moderate' do
+          errata_level 'moderate'
+        end
+        ```
+      DOC
 
       property :errata_level, String,
         coerce: proc { |x| x.downcase },
@@ -32,12 +41,8 @@ class Chef
         description: "An optional property for specifying the errata level of packages to install if it differs from the resource block's name.",
         name_property: true
 
-      action :install do
-        description "Install all packages of the specified errata level."
-
-        if rhel6?
-          yum_package "yum-plugin-security"
-        end
+      action :install, description: "Install all packages of the specified errata level." do
+        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_register.rb

@@ -27,6 +27,16 @@ class Chef
 
       description "Use the **rhsm_register** resource to register a node with the Red Hat Subscription Manager or a local Red Hat Satellite server."
       introduced "14.0"
+      examples <<~DOC
+        **Register a node with RHSM*
+
+        ```ruby
+        rhsm_register 'my-host' do
+          activation_key 'ABCD1234'
+          organization 'my_org'
+        end
+        ```
+      DOC
 
       property :activation_key, [String, Array],
         coerce: proc { |x| Array(x) },
@@ -69,9 +79,7 @@ class Chef
         default: false, desired_state: false,
         introduced: "15.9"
 
-      action :register do
-        description "Register the node with RHSM."
-
+      action :register, description: "Register the node with RHSM." do
         package "subscription-manager"
 
         unless new_resource.satellite_host.nil? || registered_with_rhsm?
@@ -106,9 +114,7 @@ class Chef
         end
       end
 
-      action :unregister do
-        description "Unregister the node from RHSM."
-
+      action :unregister, description: "Unregister the node from RHSM." do
         execute "Unregister from RHSM" do
           command "subscription-manager unregister"
           default_env true

data/lib/chef/resource/rhsm_repo.rb

@@ -26,14 +26,27 @@ 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.",
         name_property: true
 
-      action :enable do
-        description "Enable a RHSM repository."
-
+      action :enable, description: "Enable a RHSM repository." do
         execute "Enable repository #{new_resource.repo_name}" do
           command "subscription-manager repos --enable=#{new_resource.repo_name}"
           default_env true
@@ -42,9 +55,7 @@ class Chef
         end
       end
 
-      action :disable do
-        description "Disable a RHSM repository."
-
+      action :disable, description: "Disable a RHSM repository." do
         execute "Enable repository #{new_resource.repo_name}" do
           command "subscription-manager repos --disable=#{new_resource.repo_name}"
           default_env true

data/lib/chef/resource/rhsm_subscription.rb

@@ -31,9 +31,7 @@ class Chef
         description: "An optional property for specifying the Pool ID if it differs from the resource block's name.",
         name_property: true
 
-      action :attach do
-        description "Attach the node to a subscription pool."
-
+      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
@@ -42,9 +40,7 @@ class Chef
         end
       end
 
-      action :remove do
-        description "Remove the node from a subscription pool."
-
+      action :remove, description: "Remove the node from a subscription pool." do
         execute "Remove subscription pool #{new_resource.pool_id}" do
           command "subscription-manager remove --serial=#{pool_serial(new_resource.pool_id)}"
           default_env true

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

@@ -112,7 +112,7 @@ class Chef
 
       property :additional_remotes, Hash,
         description: "A Hash of additional remotes that are added to the git repository configuration.",
-        default: lazy { {} }
+        default: {}
 
       property :depth, Integer,
         description: "The number of past revisions to be included in the git shallow clone. Unless specified the default behavior will do a full clone."

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

@@ -71,12 +71,12 @@ class Chef
 
       property :users, [String, Array],
         description: "User(s) to provide sudo privileges to. This property accepts either an array or a comma separated list.",
-        default: lazy { [] },
+        default: [],
         coerce: proc { |x| x.is_a?(Array) ? x : x.split(/\s*,\s*/) }
 
       property :groups, [String, Array],
         description: "Group(s) to provide sudo privileges to. This property accepts either an array or a comma separated list. Leading % on group names is optional.",
-        default: lazy { [] },
+        default: [],
         coerce: proc { |x| coerce_groups(x) }
 
       property :commands, Array,
@@ -108,11 +108,11 @@ class Chef
 
       property :defaults, Array,
         description: "An array of defaults for the user/group.",
-        default: lazy { [] }
+        default: []
 
       property :command_aliases, Array,
         description: "Command aliases that can be used as allowed commands later in the configuration.",
-        default: lazy { [] }
+        default: []
 
       property :setenv, [TrueClass, FalseClass],
         description: "Determines whether or not to permit preservation of the environment with `sudo -E`.",
@@ -120,11 +120,11 @@ class Chef
 
       property :env_keep_add, Array,
         description: "An array of strings to add to `env_keep`.",
-        default: lazy { [] }
+        default: []
 
       property :env_keep_subtract, Array,
         description: "An array of strings to remove from `env_keep`.",
-        default: lazy { [] }
+        default: []
 
       property :visudo_path, String,
         deprecated: true
@@ -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