chef 16.13.16 → 17.0.242

data/lib/chef/resource/lwrp_base.rb

@@ -53,6 +53,10 @@ class Chef
           resource_class.run_context = run_context
           resource_class.class_from_file(filename)
 
+          unless resource_class.unified_mode
+            Chef.deprecated :unified_mode, "The #{resource_name} resource in the #{cookbook_name} cookbook should declare `unified_mode true`"
+          end
+
           # Make a useful string for the class (rather than <Class:312894723894>)
           resource_class.instance_eval do
             define_singleton_method(:to_s) do

data/lib/chef/resource/macos_userdefaults.rb

@@ -97,29 +97,29 @@ class Chef
         desired_state: false
 
       property :sudo, [TrueClass, FalseClass],
-        description: "Set to true if the setting you wish to modify requires privileged access. This requires passwordless sudo for the '/usr/bin/defaults' command to be setup for the user running #{ChefUtils::Dist::Infra::PRODUCT}.",
+        description: "Set to true if the setting you wish to modify requires privileged access. This requires passwordless sudo for the `/usr/bin/defaults` command to be setup for the user running #{ChefUtils::Dist::Infra::PRODUCT}.",
         default: false,
         desired_state: false
 
-      load_current_value do |desired|
-        Chef::Log.debug "#load_current_value: shelling out \"#{defaults_export_cmd(desired).join(" ")}\" to determine state"
-        state = shell_out(defaults_export_cmd(desired), user: desired.user)
+      load_current_value do |new_resource|
+        Chef::Log.debug "#load_current_value: shelling out \"#{defaults_export_cmd(new_resource).join(" ")}\" to determine state"
+        state = shell_out(defaults_export_cmd(new_resource), user: new_resource.user)
 
         if state.error? || state.stdout.empty?
-          Chef::Log.debug "#load_current_value: #{defaults_export_cmd(desired).join(" ")} returned stdout: #{state.stdout} and stderr: #{state.stderr}"
+          Chef::Log.debug "#load_current_value: #{defaults_export_cmd(new_resource).join(" ")} returned stdout: #{state.stdout} and stderr: #{state.stderr}"
           current_value_does_not_exist!
         end
 
         plist_data = ::Plist.parse_xml(state.stdout)
 
         # handle the situation where the key doesn't exist in the domain
-        if plist_data.key?(desired.key)
-          key desired.key
+        if plist_data.key?(new_resource.key)
+          key new_resource.key
         else
           current_value_does_not_exist!
         end
 
-        value plist_data[desired.key]
+        value plist_data[new_resource.key]
       end
 
       #
@@ -140,9 +140,7 @@ class Chef
         state_cmd
       end
 
-      action :write do
-        description "Write the value to the specified domain/key."
-
+      action :write, description: "Write the value to the specified domain/key" do
         converge_if_changed do
           cmd = defaults_modify_cmd
           Chef::Log.debug("Updating defaults value by shelling out: #{cmd.join(" ")}")
@@ -151,9 +149,7 @@ class Chef
         end
       end
 
-      action :delete do
-        description "Delete a key from a domain."
-
+      action :delete, description: "Delete a key from a domain" do
         # if it's not there there's nothing to remove
         return unless current_resource
 

data/lib/chef/resource/mdadm.rb

@@ -31,6 +31,52 @@ class Chef
                   " reboot. If the config file is required, it must be done by specifying a template with the correct array layout,"\
                   " and then by using the mount provider to create a file systems table (fstab) entry."
 
+      examples <<~DOC
+      **Create and assemble a RAID 0 array**
+
+      The mdadm command can be used to create RAID arrays. For example, a RAID 0 array named /dev/md0 with 10 devices would have a command similar to the following:
+
+      ```
+      mdadm --create /dev/md0 --level=0 --raid-devices=10 /dev/s01.../dev/s10
+      ```
+
+      where /dev/s01 .. /dev/s10 represents 10 devices (01, 02, 03, and so on). This same command, when expressed as a recipe using the mdadm resource, would be similar to:
+
+      ```ruby
+      mdadm '/dev/md0' do
+        devices [ '/dev/s01', ... '/dev/s10' ]
+        level 0
+        action :create
+      end
+      ```
+
+      (again, where /dev/s01 .. /dev/s10 represents devices /dev/s01, /dev/s02, /dev/s03, and so on).
+
+      **Create and assemble a RAID 1 array**
+
+      ```ruby
+      mdadm '/dev/md0' do
+        devices [ '/dev/sda', '/dev/sdb' ]
+        level 1
+        action [ :create, :assemble ]
+      end
+      ```
+
+      **Create and assemble a RAID 5 array**
+
+      The mdadm command can be used to create RAID arrays. For example, a RAID 5 array named /dev/sd0 with 4, and a superblock type of 0.90 would be similar to:
+
+      ```ruby
+      mdadm '/dev/sd0' do
+        devices [ '/dev/s1', '/dev/s2', '/dev/s3', '/dev/s4' ]
+        level 5
+        metadata '0.90'
+        chunk 32
+        action :create
+      end
+      ```
+      DOC
+
       default_action :create
       allowed_actions :create, :assemble, :stop
 
@@ -39,7 +85,7 @@ class Chef
         description: "The chunk size. This property should not be used for a RAID 1 mirrored pair (i.e. when the `level` property is set to `1`)."
 
       property :devices, Array,
-        default: lazy { [] },
+        default: [],
         description: "The devices to be part of a RAID array."
 
       # @todo this should get refactored away
@@ -78,7 +124,7 @@ class Chef
         end
       end
 
-      action :create do
+      action :create, description: "Create an array with per-device superblocks. If an array already exists (but does not match), update that array to match." do
         unless current_resource.exists
           converge_by("create RAID device #{new_resource.raid_device}") do
             command = "yes | mdadm --create #{new_resource.raid_device} --level #{new_resource.level}"
@@ -92,11 +138,11 @@ class Chef
             logger.info("#{new_resource} created raid device (#{new_resource.raid_device})")
           end
         else
-          logger.trace("#{new_resource} raid device already exists, skipping create (#{new_resource.raid_device})")
+          logger.debug("#{new_resource} raid device already exists, skipping create (#{new_resource.raid_device})")
         end
       end
 
-      action :assemble do
+      action :assemble, description: "Assemble a previously created array into an active array." do
         unless current_resource.exists
           converge_by("assemble RAID device #{new_resource.raid_device}") do
             command = "yes | mdadm --assemble #{new_resource.raid_device} #{new_resource.devices.join(" ")}"
@@ -105,11 +151,11 @@ class Chef
             logger.info("#{new_resource} assembled raid device (#{new_resource.raid_device})")
           end
         else
-          logger.trace("#{new_resource} raid device already exists, skipping assemble (#{new_resource.raid_device})")
+          logger.debug("#{new_resource} raid device already exists, skipping assemble (#{new_resource.raid_device})")
         end
       end
 
-      action :stop do
+      action :stop, description: "Stop an active array." do
         if current_resource.exists
           converge_by("stop RAID device #{new_resource.raid_device}") do
             command = "yes | mdadm --stop #{new_resource.raid_device}"
@@ -118,7 +164,7 @@ class Chef
             logger.info("#{new_resource} stopped raid device (#{new_resource.raid_device})")
           end
         else
-          logger.trace("#{new_resource} raid device doesn't exist (#{new_resource.raid_device}) - not stopping")
+          logger.debug("#{new_resource} raid device doesn't exist (#{new_resource.raid_device}) - not stopping")
         end
       end
 

data/lib/chef/resource/mount.rb

@@ -34,6 +34,7 @@ class Chef
       property :supports, [Array, Hash],
         description: "Specify a Hash of supported mount features.",
         default: lazy { { remount: false } },
+        default_description: "{ remount: false }",
         coerce: proc { |x| x.is_a?(Array) ? x.each_with_object({}) { |i, m| m[i] = true } : x }
 
       property :password, String,
@@ -45,7 +46,7 @@ class Chef
                description: "The directory (or path) in which the device is to be mounted. Defaults to the name of the resource block if not provided."
 
       property :device, String, identity: true,
-               description: "Required for :umount and :remount actions (for the purpose of checking the mount command output for presence). The special block device or remote node, a label, or a uuid to be mounted."
+               description: "Required for `:umount` and `:remount` actions (for the purpose of checking the mount command output for presence). The special block device or remote node, a label, or a uuid to be mounted."
 
       property :device_type, [String, Symbol],
         description: "The type of device: :device, :label, or :uuid",

data/lib/chef/resource/openssl_ec_private_key.rb

@@ -31,7 +31,7 @@ class Chef
       description "Use the **openssl_ec_private_key** resource to generate an elliptic curve (EC) private key file. If a valid EC key file can be opened at the specified location, no new file will be created. If the EC key file cannot be opened, either because it does not exist or because the password to the EC key file does not match the password in the recipe, then it will be overwritten."
       introduced "14.4"
       examples <<~DOC
-        Generate a new ec privatekey with prime256v1 key curve and default des3 cipher
+        **Generate a new ec privatekey with prime256v1 key curve and default des3 cipher**
 
         ```ruby
         openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do
@@ -41,7 +41,7 @@ class Chef
         end
         ```
 
-        Generate a new ec private key with prime256v1 key curve and aes-128-cbc cipher
+        **Generate a new ec private key with prime256v1 key curve and aes-128-cbc cipher**
 
         ```ruby
         openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do

data/lib/chef/resource/openssl_rsa_private_key.rb

@@ -43,7 +43,7 @@ class Chef
         Generate new 1024bit key with the aes-128-cbc cipher
 
         ```ruby
-        openssl_rsa_key '/etc/ssl_files/rsakey_aes128cbc.pem' do
+        openssl_rsa_private_key '/etc/ssl_files/rsakey_aes128cbc.pem' do
           key_length 1024
           key_cipher 'aes-128-cbc'
           action :create

data/lib/chef/resource/openssl_x509_certificate.rb

@@ -108,11 +108,11 @@ class Chef
 
       property :extensions, Hash,
         description: "Hash of X509 Extensions entries, in format `{ 'keyUsage' => { 'values' => %w( keyEncipherment digitalSignature), 'critical' => true } }`.",
-        default: lazy { {} }
+        default: {}
 
       property :subject_alt_name, Array,
         description: "Array of Subject Alternative Name entries, in format `DNS:example.com` or `IP:1.2.3.4`.",
-        default: lazy { [] }
+        default: []
 
       property :key_file, String,
         description: "The path to a certificate key file on the filesystem. If the key_file property is specified, the resource will attempt to source a key from this location. If no key file is found, the resource will generate a new key file at this location. If the key_file property is not specified, the resource will generate a key file in the same directory as the generated certificate, with the same name as the generated certificate."

data/lib/chef/resource/plist.rb

@@ -64,20 +64,20 @@ 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
 

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

data/lib/chef/resource/rhsm_errata.rb

@@ -25,12 +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
+      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

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,7 +41,7 @@ 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
+      action :install, description: "Install all packages of the specified errata level." do
         description "Install all packages of the specified errata level."
 
         if rhel6?

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

@@ -31,9 +31,7 @@ class Chef
         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 +40,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/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