chef 16.0.257 → 16.2.44

data/lib/chef/resource/batch.rb

@@ -25,10 +25,12 @@ class Chef
 
       provides :batch
 
-      description "Use the batch resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), 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 to guard this resource for idempotence."
+      description "Use the **batch** resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource creates and executes a temporary file (similar to how the script resource behaves), 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 to guard this resource for idempotence."
 
-      def initialize(name, run_context = nil)
-        super(name, run_context, nil, "cmd.exe")
+      def initialize(*args)
+        super
+        @interpreter = "cmd.exe"
+        @default_guard_interpreter = resource_name
       end
 
     end

data/lib/chef/resource/bff_package.rb

@@ -25,7 +25,7 @@ class Chef
 
       provides :bff_package
 
-      description "Use the bff_package resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
+      description "Use the **bff_package** resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources."
       introduced "12.0"
 
       property :package_name, String,

data/lib/chef/resource/breakpoint.rb

@@ -26,7 +26,7 @@ class Chef
 
       provides :breakpoint, target_mode: true
 
-      description "Use the breakpoint resource to add breakpoints to recipes. Run the #{Chef::Dist::SHELL} in #{Chef::Dist::PRODUCT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{Chef::Dist::CLIENT} during an actual #{Chef::Dist::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
+      description "Use the **breakpoint** resource to add breakpoints to recipes. Run the #{Chef::Dist::SHELL} in #{Chef::Dist::PRODUCT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{Chef::Dist::CLIENT} during an actual #{Chef::Dist::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
       introduced "12.0"
 
       default_action :break

data/lib/chef/resource/build_essential.rb

@@ -24,22 +24,25 @@ class Chef
 
       provides(:build_essential) { true }
 
-      description "Use the build_essential resource to install the packages required for compiling C software from source."
+      description "Use the **build_essential** resource to install the packages required for compiling C software from source."
       introduced "14.0"
       examples <<~DOC
-        Install compilation packages
+        **Install compilation packages**:
+
         ```ruby
         build_essential
         ```
 
-        Install compilation packages during the compilation phase
+        **Install compilation packages during the compilation phase**:
+
         ```ruby
         build_essential 'Install compilation tools' do
           compile_time true
         end
         ```
 
-        Upgrade compilation packages on macOS systems
+        **Upgrade compilation packages on macOS systems**:
+
         ```ruby
         build_essential 'Install compilation tools' do
           action :upgrade
@@ -52,6 +55,7 @@ class Chef
 
       property :raise_if_unsupported, [TrueClass, FalseClass],
         description: "Raise a hard error on platforms where this resource is unsupported.",
+        introduced: "15.5",
         default: false, desired_state: false # FIXME: make this default to true
 
       action :install do

data/lib/chef/resource/cab_package.rb

@@ -27,7 +27,7 @@ class Chef
 
       provides :cab_package
 
-      description "Use the cab_package resource to install or remove Microsoft Windows cabinet (.cab) packages."
+      description "Use the **cab_package** resource to install or remove Microsoft Windows cabinet (.cab) packages."
       introduced "12.15"
 
       allowed_actions :install, :remove

data/lib/chef/resource/chef_client_cron.rb

@@ -26,23 +26,26 @@ class Chef
 
       provides :chef_client_cron
 
-      description "Use the chef_client_cron resource to setup the #{Chef::Dist::PRODUCT} to run as a cron job. This resource will also create the specified log directory if it doesn't already exist."
+      description "Use the **chef_client_cron** resource to setup the #{Chef::Dist::PRODUCT} to run as a cron job. This resource will also create the specified log directory if it doesn't already exist."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
-      chef_client_cron "Run chef-client as a cron job"
+      chef_client_cron "Run #{Chef::Dist::PRODUCT} as a cron job"
       ```
 
-      Run #{Chef::Dist::PRODUCT} twice a day
+      **Run #{Chef::Dist::PRODUCT} twice a day**:
+
       ```ruby
-      chef_client_cron "Run chef-client every 12 hours" do
+      chef_client_cron "Run #{Chef::Dist::PRODUCT} every 12 hours" do
         minute 0
         hour "0,12"
       end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::PRODUCT} with extra options passed to the client**:
+
       ```ruby
       chef_client_cron "Run an override recipe" do
         daemon_options ["--override-runlist mycorp_base::default"]
@@ -133,14 +136,14 @@ class Chef
 
       property :environment, Hash,
         default: lazy { {} },
-        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``."
+        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`."
 
       action :add 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
             owner new_resource.user
-            mode "0640"
+            mode "0750"
             recursive true
           end
         end
@@ -160,7 +163,7 @@ class Chef
       end
 
       action :remove do
-        cron_d new_resource.job_name do
+        declare_resource(cron_resource_type, new_resource.job_name) do
           action :delete
         end
       end

data/lib/chef/resource/chef_client_scheduled_task.rb

@@ -24,27 +24,40 @@ class Chef
 
       provides :chef_client_scheduled_task
 
-      description "Use the chef_client_cron resource to setup the #{Chef::Dist::PRODUCT} to run as a Windows scheduled task. This resource will also create the specified log directory if it doesn't already exist."
+      description "Use the **chef_client_scheduled_task** resource to setup the #{Chef::Dist::PRODUCT} to run as a Windows scheduled task. This resource will also create the specified log directory if it doesn't already exist."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
-        chef_client_scheduled_task "Run chef-client as a scheduled task"
+        chef_client_scheduled_task "Run #{Chef::Dist::PRODUCT} as a scheduled task"
       ```
 
-      Run #{Chef::Dist::PRODUCT} on system start
+      **Run #{Chef::Dist::PRODUCT} on system start**:
+
       ```ruby
-        chef_client_scheduled_task 'Chef Client on start' do
+        chef_client_scheduled_task '#{Chef::Dist::PRODUCT} on start' do
           frequency 'onstart'
         end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::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
       ```
+
+      **Run #{Chef::Dist::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
+      ```
       DOC
 
       resource_name :chef_client_scheduled_task
@@ -69,7 +82,8 @@ class Chef
         coerce: proc { |x| Integer(x) },
         callbacks: { "should be a positive number" => proc { |v| v > 0 } },
         description: "Numeric value to go with the scheduled task frequency",
-        default: 30
+        default: lazy { frequency == "minute" ? 30 : 1 },
+        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/>",
@@ -126,6 +140,7 @@ class Chef
 
         # According to https://docs.microsoft.com/en-us/windows/desktop/taskschd/schtasks,
         # the :once, :onstart, :onlogon, and :onidle schedules don't accept schedule modifiers
+
         windows_task new_resource.task_name do
           run_level                      :highest
           command                        full_command

data/lib/chef/resource/chef_client_systemd_timer.rb

@@ -24,22 +24,25 @@ class Chef
 
       provides :chef_client_systemd_timer
 
-      description "Use the chef_client_systemd_timer resource to setup the #{Chef::Dist::PRODUCT} to run as a systemd timer."
+      description "Use the **chef_client_systemd_timer** resource to setup the #{Chef::Dist::PRODUCT} to run as a systemd timer."
       introduced "16.0"
       examples <<~DOC
-      Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence
+      **Setup #{Chef::Dist::PRODUCT} to run using the default 30 minute cadence**:
+
       ```ruby
-      chef_client_systemd_timer "Run chef-client as a systemd timer"
+      chef_client_systemd_timer "Run #{Chef::Dist::PRODUCT} as a systemd timer"
       ```
 
-      Run #{Chef::Dist::PRODUCT} every 1 hour
+      **Run #{Chef::Dist::PRODUCT} every 1 hour**:
+
       ```ruby
-      chef_client_systemd_timer "Run chef-client every 1 hour" do
+      chef_client_systemd_timer "Run #{Chef::Dist::PRODUCT} every 1 hour" do
         interval "1hr"
       end
       ```
 
-      Run #{Chef::Dist::PRODUCT} with extra options passed to the client
+      **Run #{Chef::Dist::PRODUCT} with extra options passed to the client**:
+
       ```ruby
       chef_client_systemd_timer "Run an override recipe" do
         daemon_options ["--override-runlist mycorp_base::default"]
@@ -92,7 +95,7 @@ class Chef
         default: lazy { [] }
 
       property :environment, Hash,
-        description: "A Hash containing additional arbitrary environment variables under which the systemd timer will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``.",
+        description: "A Hash containing additional arbitrary environment variables under which the systemd timer will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`.",
         default: lazy { {} }
 
       action :add do

data/lib/chef/resource/chef_gem.rb

@@ -34,6 +34,10 @@ class Chef
     #    installed
     #  - Runs Gem.clear_paths after the action, ensuring that gem is aware of changes so that it can be required
     #    immediately after it is installed
+
+    require_relative "gem_package"
+    require_relative "../dist"
+
     class ChefGem < Chef::Resource::Package::GemPackage
       unified_mode true
       provides :chef_gem
@@ -45,8 +49,8 @@ class Chef
       property :version, String,
         description: "The version of a package to be installed or upgraded."
 
-      property :gem_binary, default: "#{RbConfig::CONFIG["bindir"]}/gem", default_description: "Chef's built-in gem binary.",
-                            description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by the #{Chef::Dist::CLIENT} will be installed.",
+      property :gem_binary, default: "#{RbConfig::CONFIG["bindir"]}/gem", default_description: "The `gem` binary included with #{Chef::Dist::PRODUCT}.",
+                            description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be installed.",
                             callbacks: {
                  "The chef_gem resource is restricted to the current gem environment, use gem_package to install to other environments." => proc { |v| v == "#{RbConfig::CONFIG["bindir"]}/gem" },
                }

data/lib/chef/resource/chef_handler.rb

@@ -25,7 +25,7 @@ class Chef
 
       provides(:chef_handler) { true }
 
-      description "Use the chef_handler resource to install or uninstall reporting/exception handlers."
+      description "Use the **chef_handler** resource to install or uninstall reporting/exception handlers."
       introduced "14.0"
 
       property :class_name, String,
@@ -107,7 +107,7 @@ class Chef
           end
         end
 
-        # Walks down the namespace heirarchy to return the class object for the given class name.
+        # Walks down the namespace hierarchy to return the class object for the given class name.
         # If the class is not available, NameError is thrown.
         #
         # @param class_full_name [String] full class name such as 'Chef::Handler::Foo' or 'MyHandler'.
@@ -118,7 +118,7 @@ class Chef
           class_name = ancestors.pop
 
           # We need to search the ancestors only for the first/uppermost namespace of the class, so we
-          # need to enable the #const_get inherit paramenter only when we are searching in Kernel scope
+          # need to enable the #const_get inherit parameter only when we are searching in Kernel scope
           # (see COOK-4117).
           parent = ancestors.inject(Kernel) { |scope, const_name| scope.const_get(const_name, scope === Kernel) }
           child = parent.const_get(class_name, parent === Kernel)

data/lib/chef/resource/chef_sleep.rb

@@ -24,22 +24,25 @@ class Chef
 
       unified_mode true
 
-      description "Use the chef_sleep resource to set the number of seconds to sleep during a #{Chef::Dist::PRODUCT} run. Only use this resource when a command or service exits successfully but is not ready for the next step of the recipe."
+      description "Use the **chef_sleep** resource to pause (sleep) for a number of seconds during a #{Chef::Dist::PRODUCT} run. Only use this resource when a command or service exits successfully but is not ready for the next step in a recipe."
       introduced "15.5"
       examples <<~DOC
-        Sleep for 10 seconds
+        **Sleep for 10 seconds**:
+
         ```ruby
         chef_sleep '10'
         ```
 
-        Sleep for 10 seconds with a descriptive resource name for logging
+        **Sleep for 10 seconds with a descriptive resource name for logging**:
+
         ```ruby
         chef_sleep 'wait for the service to start' do
           seconds 10
         end
         ````
 
-        Use a notification from another resource to sleep only when necessary
+        **Use a notification from another resource to sleep only when necessary**:
+
         ```ruby
         service 'Service that is slow to start and reports as started' do
           service_name 'my_database'

data/lib/chef/resource/chef_vault_secret.rb

@@ -26,9 +26,9 @@ class Chef
       provides :chef_vault_secret
 
       introduced "16.0"
-      description "Use the chef_vault_secret resource to store secrets in Chef Vault items. Where possible and relevant, this resource attempts to map behavior and functionality to the knife vault sub-commands."
+      description "Use the **chef_vault_secret** resource to store secrets in Chef Vault items. Where possible and relevant, this resource attempts to map behavior and functionality to the knife vault sub-commands."
       examples <<~DOC
-        To create a 'foo' item in an existing 'bar' data bag:
+        **To create a 'foo' item in an existing 'bar' data bag**:
 
         ```ruby
         chef_vault_secret 'foo' do
@@ -39,13 +39,13 @@ class Chef
         end
         ```
 
-        To allow multiple admins access to an item:
+        **To allow multiple admins access to an item**:
 
         ```ruby
         chef_vault_secret 'root-password' do
           admins 'jtimberman,paulmooring'
           data_bag 'secrets'
-          raw_data({'auth' => 'DontUseThisPasswordForRoot'})
+          raw_data({'auth' => 'DoNotUseThisPasswordForRoot'})
           search '*:*'
         end
         ```

data/lib/chef/resource/chocolatey_config.rb

@@ -21,10 +21,11 @@ class Chef
 
       provides :chocolatey_config
 
-      description "Use the chocolatey_config resource to add or remove Chocolatey configuration keys."
+      description "Use the **chocolatey_config** resource to add or remove Chocolatey configuration keys."
       introduced "14.3"
       examples <<~DOC
-        Set the Chocolatey cacheLocation config
+        **Set the Chocolatey cacheLocation config**:
+
         ```ruby
         chocolatey_config 'Set cacheLocation config' do
           config_key 'cacheLocation'
@@ -32,7 +33,8 @@ class Chef
         end
         ```
 
-        Unset a Chocolatey config
+        **Unset a Chocolatey config**:
+
         ```ruby
         chocolatey_config 'BogusConfig' do
           action :unset

data/lib/chef/resource/chocolatey_feature.rb

@@ -20,17 +20,19 @@ class Chef
       unified_mode true
       provides :chocolatey_feature
 
-      description "Use the chocolatey_feature resource to enable and disable Chocolatey features."
+      description "Use the **chocolatey_feature** resource to enable and disable Chocolatey features."
       introduced "15.1"
       examples <<~DOC
-        Enable the checksumFiles Chocolatey feature
+        **Enable the checksumFiles Chocolatey feature**
+
         ```ruby
         chocolatey_feature 'checksumFiles' do
           action :enable
         end
         ```
 
-        Disable the checksumFiles Chocolatey feature
+        **Disable the checksumFiles Chocolatey feature**
+
         ```ruby
         chocolatey_feature 'checksumFiles' do
           action :disable

data/lib/chef/resource/chocolatey_package.rb

@@ -25,17 +25,19 @@ class Chef
 
       provides :chocolatey_package
 
-      description "Use the chocolatey_package resource to manage packages using Chocolatey on the Microsoft Windows platform."
+      description "Use the **chocolatey_package** resource to manage packages using Chocolatey on the Microsoft Windows platform. Note: The Chocolatey package manager is not installed on Windows by default. You will need to install it prior to using this resource by adding the [Chocolatey cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's run list."
       introduced "12.7"
       examples <<~DOC
-        Install a Chocolatey package
+        **Install a Chocolatey package**:
+
         ```ruby
         chocolatey_package 'name of package' do
           action :install
         end
         ```
 
-        Install a package with options with Chocolatey's ``--checksum`` option
+        **Install a package with options with Chocolatey's `--checksum` option**:
+
         ```ruby
         chocolatey_package 'name of package' do
           options '--checksum 1234567890'

data/lib/chef/resource/chocolatey_source.rb

@@ -20,10 +20,11 @@ class Chef
       unified_mode true
       provides :chocolatey_source
 
-      description "Use the chocolatey_source resource to add, remove, enable, or disable Chocolatey sources."
+      description "Use the **chocolatey_source** resource to add, remove, enable, or disable Chocolatey sources."
       introduced "14.3"
       examples <<~DOC
-        Add a Chocolatey source
+        **Add a Chocolatey source**
+
         ```ruby
         chocolatey_source 'MySource' do
           source 'http://example.com/something'
@@ -31,7 +32,8 @@ class Chef
         end
         ```
 
-        Remove a Chocolatey source
+        **Remove a Chocolatey source**
+
         ```ruby
         chocolatey_source 'MySource' do
           action :remove