chef 17.0.242 → 17.4.25

data/lib/chef/resource/build_essential.rb

@@ -57,7 +57,7 @@ class Chef
         introduced: "15.5",
         default: false, desired_state: false # FIXME: make this default to true
 
-      action :install, description: "Install build essential packages" do
+      action :install, description: "Install build essential packages." do
         case
         when debian?
           package %w{ autoconf binutils-doc bison build-essential flex gettext ncurses-dev }

data/lib/chef/resource/chef_client_config.rb

@@ -29,7 +29,7 @@ class Chef
       examples <<~DOC
       **Bare minimum #{ChefUtils::Dist::Infra::PRODUCT} client.rb**:
 
-      The absolute minimum configuration necessary for a node to communicate with the Infra Server is the URL of the Infra Server. All other configuration options either have values at the server side (Policyfiles, Roles, Environments, etc) or have default values determined at client startup.
+      The absolute minimum configuration necessary for a node to communicate with the #{ChefUtils::Dist::Server::PRODUCT} is the URL of the #{ChefUtils::Dist::Server::PRODUCT}. All other configuration options either have values at the server side (Policyfiles, Roles, Environments, etc) or have default values determined at client startup.
 
       ```ruby
       chef_client_config 'Create client.rb' do
@@ -139,7 +139,7 @@ class Chef
         DESC
 
       property :formatters, Array,
-        description: "",
+        description: "Client logging formatters to load.",
         default: []
 
       property :event_loggers, Array,
@@ -184,6 +184,10 @@ class Chef
         coerce: proc { |x| x.map { |v| string_to_symbol(v).capitalize } },
         default: []
 
+      property :policy_persist_run_list, [true, false],
+        description: "Override run lists defined in a Policyfile with the `run_list` defined on the #{ChefUtils::Dist::Server::PRODUCT}.",
+        introduced: "17.3"
+
       property :minimal_ohai, [true, false],
         description: "Run a minimal set of Ohai plugins providing data necessary for the execution of #{ChefUtils::Dist::Infra::PRODUCT}'s built-in resources. Setting this to true will skip many large and time consuming data sets such as `cloud` or `packages`. Setting this this to true may break cookbooks that assume all Ohai data will be present."
 
@@ -227,7 +231,7 @@ class Chef
       property :additional_config, String,
         description: "Additional text to add at the bottom of the client.rb config. This can be used to run custom Ruby or to add less common config options"
 
-      action :create, description: "Create a client.rb config file" do
+      action :create, description: "Create a client.rb config file for configuring #{ChefUtils::Dist::Infra::PRODUCT}." do
         unless ::Dir.exist?(new_resource.config_directory)
           directory new_resource.config_directory do
             user new_resource.user unless new_resource.user.nil?
@@ -277,14 +281,15 @@ class Chef
             report_handlers: format_handler(new_resource.report_handlers),
             ssl_verify_mode: new_resource.ssl_verify_mode,
             start_handlers: format_handler(new_resource.start_handlers),
-            additional_config: new_resource.additional_config
+            additional_config: new_resource.additional_config,
+            policy_persist_run_list: new_resource.policy_persist_run_list
           )
           mode "0640"
           action :create
         end
       end
 
-      action :remove, description: "Remove a client.rb config file" do
+      action :remove, description: "Remove a client.rb config file for configuring #{ChefUtils::Dist::Infra::PRODUCT}." do
         file ::File.join(new_resource.config_directory, "client.rb") do
           action :delete
         end

data/lib/chef/resource/chef_client_cron.rb

@@ -106,7 +106,7 @@ class Chef
         description: "The e-mail address to e-mail any cron task failures to."
 
       property :accept_chef_license, [true, false],
-        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement/>",
+        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement>",
         default: false
 
       property :config_directory, String,
@@ -144,7 +144,7 @@ class Chef
         coerce: proc { |x| Integer(x) },
         callbacks: { "should be an Integer between -20 and 19" => proc { |v| v >= -20 && v <= 19 } }
 
-      action :add, description: "Add a cron job to run #{ChefUtils::Dist::Infra::PRODUCT}" do
+      action :add, description: "Add a cron job to run #{ChefUtils::Dist::Infra::PRODUCT}." do
         # TODO: Replace this with a :create_if_missing action on directory when that exists
         unless ::Dir.exist?(new_resource.log_directory)
           directory new_resource.log_directory do
@@ -168,7 +168,7 @@ class Chef
         end
       end
 
-      action :remove, description: "Remove a cron job for #{ChefUtils::Dist::Infra::PRODUCT}" do
+      action :remove, description: "Remove a cron job for #{ChefUtils::Dist::Infra::PRODUCT}." do
         declare_resource(cron_resource_type, new_resource.job_name) do
           action :delete
         end

data/lib/chef/resource/chef_client_launchd.rb

@@ -65,7 +65,7 @@ class Chef
         description: "A random number of seconds between 0 and X to add to interval so that all #{ChefUtils::Dist::Infra::CLIENT} commands don't execute at the same time."
 
       property :accept_chef_license, [true, false],
-        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement/>",
+        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement>",
         default: false
 
       property :config_directory, String,
@@ -101,7 +101,7 @@ class Chef
         description: "Run the #{ChefUtils::Dist::Infra::CLIENT} process with low priority disk IO",
         default: true
 
-      action :enable do
+      action :enable, description: "Enable running #{ChefUtils::Dist::Infra::PRODUCT} on a schedule using launchd." do
         unless ::Dir.exist?(new_resource.log_directory)
           directory new_resource.log_directory do
             owner new_resource.user
@@ -148,7 +148,7 @@ class Chef
         end
       end
 
-      action :disable do
+      action :disable, description: "Disable running #{ChefUtils::Dist::Infra::PRODUCT} on a schedule using launchd" do
         service ChefUtils::Dist::Infra::PRODUCT do
           service_name "com.#{ChefUtils::Dist::Infra::SHORT}.#{ChefUtils::Dist::Infra::CLIENT}"
           action :disable

data/lib/chef/resource/chef_client_scheduled_task.rb

@@ -30,33 +30,33 @@ class Chef
       **Setup #{ChefUtils::Dist::Infra::PRODUCT} to run using the default 30 minute cadence**:
 
       ```ruby
-        chef_client_scheduled_task 'Run #{ChefUtils::Dist::Infra::PRODUCT} as a scheduled task'
+      chef_client_scheduled_task 'Run #{ChefUtils::Dist::Infra::PRODUCT} as a scheduled task'
       ```
 
       **Run #{ChefUtils::Dist::Infra::PRODUCT} on system start**:
 
       ```ruby
-        chef_client_scheduled_task '#{ChefUtils::Dist::Infra::PRODUCT} on start' do
-          frequency 'onstart'
-        end
+      chef_client_scheduled_task '#{ChefUtils::Dist::Infra::PRODUCT} on start' do
+        frequency 'onstart'
+      end
       ```
 
       **Run #{ChefUtils::Dist::Infra::PRODUCT} with extra options passed to the client**:
 
       ```ruby
-        chef_client_scheduled_task 'Run an override recipe' do
-          daemon_options ['--override-runlist mycorp_base::default']
-        end
+      chef_client_scheduled_task 'Run an override recipe' do
+        daemon_options ['--override-runlist mycorp_base::default']
+      end
       ```
 
       **Run #{ChefUtils::Dist::Infra::PRODUCT} daily at 01:00 am, specifying a named run-list**:
 
       ```ruby
-        chef_client_scheduled_task 'Run chef-client named run-list daily' do
-          frequency 'daily'
-          start_time '01:00'
-          daemon_options ['-n audit_only']
-        end
+      chef_client_scheduled_task 'Run chef-client named run-list daily' do
+        frequency 'daily'
+        start_time '01:00'
+        daemon_options ['-n audit_only']
+      end
       ```
       DOC
 
@@ -87,7 +87,7 @@ class Chef
         default_description: "30 if frequency is 'minute', 1 otherwise"
 
       property :accept_chef_license, [true, false],
-        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement/>",
+        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement>",
         default: false
 
       property :start_date, String,
@@ -129,7 +129,7 @@ class Chef
         description: "An array of options to pass to the #{ChefUtils::Dist::Infra::CLIENT} command.",
         default: []
 
-      action :add do
+      action :add, description: "Add a Windows Scheduled Task that runs #{ChefUtils::Dist::Infra::PRODUCT}." do
         # TODO: Replace this with a :create_if_missing action on directory when that exists
         unless Dir.exist?(new_resource.log_directory)
           directory new_resource.log_directory do
@@ -157,7 +157,7 @@ class Chef
         end
       end
 
-      action :remove do
+      action :remove, description: "Remove a Windows Scheduled Task that runs #{ChefUtils::Dist::Infra::PRODUCT}." do
         windows_task new_resource.task_name do
           action :delete
         end

data/lib/chef/resource/chef_client_systemd_timer.rb

@@ -75,7 +75,7 @@ class Chef
         default: "5min"
 
       property :accept_chef_license, [true, false],
-        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement/>",
+        description: "Accept the Chef Online Master License and Services Agreement. See <https://www.chef.io/online-master-agreement>",
         default: false
 
       property :run_on_battery, [true, false],
@@ -104,7 +104,7 @@ class Chef
         coerce: proc { |x| Integer(x) },
         callbacks: { "should be a positive Integer" => proc { |v| v > 0 } }
 
-      action :add do
+      action :add, description: "Add a systemd timer that runs #{ChefUtils::Dist::Infra::PRODUCT}." do
         systemd_unit "#{new_resource.job_name}.service" do
           content service_content
           action :create
@@ -116,7 +116,7 @@ class Chef
         end
       end
 
-      action :remove do
+      action :remove, description: "Remove a systemd timer that runs #{ChefUtils::Dist::Infra::PRODUCT}." do
         systemd_unit "#{new_resource.job_name}.service" do
           action :delete
         end

data/lib/chef/resource/chef_client_trusted_certificate.rb

@@ -64,7 +64,7 @@ class Chef
       property :certificate, String, required: [:add],
         description: "The text of the certificate file including the BEGIN/END comment lines."
 
-      action :add do
+      action :add, description: "Add a trusted certificate to #{ChefUtils::Dist::Infra::PRODUCT}'s trusted certificate directory" do
         unless ::Dir.exist?(Chef::Config[:trusted_certs_dir])
           directory Chef::Config[:trusted_certs_dir] do
             mode "0640"
@@ -78,7 +78,7 @@ class Chef
         end
       end
 
-      action :remove do
+      action :remove, description: "Remove a trusted certificate from #{ChefUtils::Dist::Infra::PRODUCT}'s trusted certificate directory" do
         file cert_path do
           action :delete
         end

data/lib/chef/resource/chef_handler.rb

@@ -194,7 +194,7 @@ class Chef
 
       # This action needs to find an rb file that presumably contains the indicated class in it and the
       # load that file. It then instantiates that class by name and registers it as a handler.
-      action :enable, description: "Enables the handler for the current #{ChefUtils::Dist::Infra::PRODUCT} run on the current node" do
+      action :enable, description: "Enables the handler for the current #{ChefUtils::Dist::Infra::PRODUCT} run on the current node." do
         class_name = new_resource.class_name
         new_resource.type.each do |type, enable|
           next unless enable
@@ -216,7 +216,7 @@ class Chef
         end
       end
 
-      action :disable, description: "Disables the handler for the current #{ChefUtils::Dist::Infra::PRODUCT} run on the current node" do
+      action :disable, description: "Disables the handler for the current #{ChefUtils::Dist::Infra::PRODUCT} run on the current node." do
         new_resource.type.each_key do |type|
           unregister_handler(type, new_resource.class_name)
         end

data/lib/chef/resource/chef_sleep.rb

@@ -62,7 +62,7 @@ class Chef
         coerce: proc { |s| Integer(s) },
         name_property: true
 
-      action :sleep, description: "Pause the #{ChefUtils::Dist::Infra::PRODUCT} run for a specified number of seconds" do
+      action :sleep, description: "Pause the #{ChefUtils::Dist::Infra::PRODUCT} run for a specified number of seconds." do
         converge_by("sleep #{new_resource.seconds} seconds") do
           sleep(new_resource.seconds)
         end

data/lib/chef/resource/chef_vault_secret.rb

@@ -33,7 +33,7 @@ class Chef
         ```ruby
         chef_vault_secret 'foo' do
           data_bag 'bar'
-          raw_data({'auth' => 'baz'})
+          raw_data({ 'auth' => 'baz' })
           admins 'jtimberman'
           search '*:*'
         end
@@ -45,7 +45,7 @@ class Chef
         chef_vault_secret 'root-password' do
           admins 'jtimberman,paulmooring'
           data_bag 'secrets'
-          raw_data({'auth' => 'DoNotUseThisPasswordForRoot'})
+          raw_data({ 'auth' => 'DoNotUseThisPasswordForRoot' })
           search '*:*'
         end
         ```

data/lib/chef/resource/chocolatey_feature.rb

@@ -65,7 +65,7 @@ class Chef
         data ? data.attribute("enabled").to_s : nil # REXML just returns nil if it can't find anything so avoid an undefined method error
       end
 
-      action :enable, description: "Enables a named Chocolatey feature" do
+      action :enable, description: "Enables a named Chocolatey feature." do
         if current_resource.feature_state != true
           converge_by("enable Chocolatey feature '#{new_resource.feature_name}'") do
             shell_out!(choco_cmd("enable"))
@@ -73,7 +73,7 @@ class Chef
         end
       end
 
-      action :disable, description: "Disables a named Chocolatey feature" do
+      action :disable, description: "Disables a named Chocolatey feature." do
         if current_resource.feature_state == true
           converge_by("disable Chocolatey feature '#{new_resource.feature_name}'") do
             shell_out!(choco_cmd("disable"))

data/lib/chef/resource/chocolatey_source.rb

@@ -98,7 +98,7 @@ class Chef
         end
       end
 
-      action :remove, description: "Removes a Chocolatey source" do
+      action :remove, description: "Removes a Chocolatey source." do
 
         if current_resource
           converge_by("remove Chocolatey source '#{new_resource.source_name}'") do

data/lib/chef/resource/cron/cron_d.rb

@@ -29,7 +29,7 @@ class Chef
       provides :cron_d
 
       introduced "14.4"
-      description "Use the **cron_d** resource to manage cron job files in the /etc/cron.d directory. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
+      description "Use the **cron_d** resource to manage cron job files in the `/etc/cron.d` directory. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
       examples <<~DOC
         **Run a program on the fifth hour of the day**
 
@@ -116,19 +116,17 @@ class Chef
       end
 
       action :create do
-        description "Add a cron definition file to /etc/cron.d."
+        description "Add a cron definition file to `/etc/cron.d`."
 
         create_template(:create)
       end
 
-      action :create_if_missing do
-        description "Add a cron definition file to /etc/cron.d, but do not update an existing file."
+      action :create_if_missing, description: "Add a cron definition file to `/etc/cron.d`, but do not update an existing file." do
 
         create_template(:create_if_missing)
       end
 
-      action :delete do
-        description "Remove a cron definition file from /etc/cron.d if it exists."
+      action :delete, description: "Remove a cron definition file from `/etc/cron.d` if it exists." do
 
         # cleanup the legacy named job if it exists
         file "legacy named cron.d file" do

data/lib/chef/resource/cron_access.rb

@@ -64,7 +64,7 @@ class Chef
           "default" => "/etc",
       }.freeze
 
-      action :allow, description: "Add the user to the cron.allow file" do
+      action :allow, description: "Add the user to the cron.allow file." do
         allow_path = ::File.join(value_for_platform_family(CRON_PATHS), "cron.allow")
 
         with_run_context :root do

data/lib/chef/resource/dmg_package.rb

@@ -121,7 +121,7 @@ class Chef
         end
       end
 
-      action :install, description: "Installs the application" do
+      action :install, description: "Installs the application." do
         if current_resource.nil?
           if new_resource.source
             remote_file dmg_file do

data/lib/chef/resource/dsc_resource.rb

@@ -74,7 +74,7 @@ class Chef
 
       property :module_version, String,
         introduced: "12.21",
-        description: "The version number of the module to use. PowerShell 5.0.10018.0 (or higher) supports having multiple versions of a module installed. This should be specified along with the module_name."
+        description: "The version number of the module to use. PowerShell 5.0.10018.0 (or higher) supports having multiple versions of a module installed. This should be specified along with the `module_name` property."
 
       def property(property_name, value = nil)
         unless property_name.is_a?(Symbol)

data/lib/chef/resource/execute.rb

@@ -304,9 +304,9 @@ class Chef
         gives a recipe full control over the command issued in a much cleaner, more
         direct manner.
 
-        **Use the search recipe DSL method to find users**:
+        **Use the search Infra Language helper to find users**:
 
-        The following example shows how to use the `search` method in the Recipe DSL to
+        The following example shows how to use the `search` method in the Chef Infra Language to
         search for users:
 
         ```ruby
@@ -515,7 +515,7 @@ class Chef
 
       property :command, [ String, Array ],
         name_property: true,
-        description: "An optional property to set the command to be executed if it differs from the resource block's name."
+        description: "An optional property to set the command to be executed if it differs from the resource block's name. Note: Use the **execute** resource to run a single command. Use multiple **execute** resource blocks to run multiple commands."
 
       property :umask, [ String, Integer ],
         description: "The file mode creation mask, or umask."
@@ -633,13 +633,13 @@ class Chef
         end
 
         # if domain is provided in both username and domain
-        if specified_user.is_a?(String) && ((specified_user.include? '\\') || (specified_user.include? "@")) && specified_domain
+        if specified_user.is_a?(String) && ((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.is_a?(String) && 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/gem_package.rb

@@ -83,7 +83,8 @@ class Chef
 
       property :clear_sources, [ TrueClass, FalseClass, nil ],
         description: "Set to `true` to download a gem from the path specified by the `source` property (and not from RubyGems).",
-        default: lazy { Chef::Config[:clear_gem_sources] }, desired_state: false
+        default: lazy { Chef::Config[:clear_gem_sources] },
+        default_description: "false unless `clear_gem_sources` set to true in the `client.rb` config.", desired_state: false
 
       property :gem_binary, String, desired_state: false,
         description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{ChefUtils::Dist::Infra::PRODUCT} will be used."

data/lib/chef/resource/group.rb

@@ -43,16 +43,16 @@ class Chef
 
       property :excluded_members, [String, Array], default: [],
                coerce: proc { |arg| arg.is_a?(String) ? arg.split(/\s*,\s*/) : arg },
-               description: "Remove users from a group. May only be used when append is set to true."
+               description: "Remove users from a group. May only be used when `append` is set to `true`."
 
       property :append, [ TrueClass, FalseClass ], default: false,
-               description: "How members should be appended and/or removed from a group. When true, members are appended and excluded_members are removed. When false, group members are reset to the value of the members property."
+               description: "How members should be appended and/or removed from a group. When true, `members` are appended and `excluded_members` are removed. When `false`, group members are reset to the value of the `members` property."
 
       property :system, [ TrueClass, FalseClass ], default: false,
-               description: "Set if a group belongs to a system group. Set to true if the group belongs to a system group."
+               description: "Set to `true` if the group belongs to a system group."
 
       property :non_unique, [ TrueClass, FalseClass ], default: false,
-               description: "Allow gid duplication. May only be used with the Groupadd provider."
+               description: "Allow gid duplication. May only be used with the `Groupadd` user resource provider."
 
       property :comment, String,
         introduced: "14.9",