chef 16.0.257 → 16.0.275

data/lib/chef/resource/apt_repository.rb

@@ -28,11 +28,12 @@ class Chef
 
       provides(:apt_repository) { true }
 
-      description "Use the apt_repository resource to specify additional APT repositories. Adding a new repository will update the APT package cache immediately."
+      description "Use the **apt_repository** resource to specify additional APT repositories. Adding a new repository will update the APT package cache immediately."
       introduced "12.9"
 
       examples <<~DOC
-        Add repository with basic settings
+        **Add repository with basic settings**:
+
          ```ruby
         apt_repository 'nginx' do
           uri        'http://nginx.org/packages/ubuntu/'
@@ -40,29 +41,32 @@ class Chef
         end
         ```
 
-        Enable Ubuntu multiverse repositories
+        **Enable Ubuntu multiverse repositories**:
+
         ```ruby
         apt_repository 'security-ubuntu-multiverse' do
           uri          'http://security.ubuntu.com/ubuntu'
-          distribution 'trusty-security'
+          distribution 'xenial-security'
           components   ['multiverse']
           deb_src      true
         end
         ```
 
-        Add the Nginx PPA, autodetect the key and repository url
+        **Add the Nginx PPA, autodetect the key and repository url**:
+
         ```ruby
         apt_repository 'nginx-php' do
           uri          'ppa:nginx/stable'
         end
         ```
 
-        Add the JuJu PPA, grab the key from the keyserver, and add source repo
+        **Add the JuJu PPA, grab the key from the keyserver, and add source repo**:
+
         ```ruby
         apt_repository 'juju' do
           uri 'http://ppa.launchpad.net/juju/stable/ubuntu'
           components ['main']
-          distribution 'trusty'
+          distribution 'xenial'
           key 'C8068B11'
           keyserver 'keyserver.ubuntu.com'
           action :add
@@ -70,7 +74,8 @@ class Chef
         end
         ```
 
-        Add repository that requires multiple keys to authenticate packages
+        **Add repository that requires multiple keys to authenticate packages**:
+
         ```ruby
         apt_repository 'rundeck' do
           uri 'https://dl.bintray.com/rundeck/rundeck-deb'
@@ -81,18 +86,20 @@ class Chef
         end
         ```
 
-        Add the Cloudera Repo of CDH4 packages for Ubuntu 12.04 on AMD64
+        **Add the Cloudera Repo of CDH4 packages for Ubuntu 16.04 on AMD64**:
+
         ```ruby
         apt_repository 'cloudera' do
-          uri          'http://archive.cloudera.com/cdh4/ubuntu/precise/amd64/cdh'
+          uri          'http://archive.cloudera.com/cdh4/ubuntu/xenial/amd64/cdh'
           arch         'amd64'
-          distribution 'precise-cdh4'
+          distribution 'xenial-cdh4'
           components   ['contrib']
           key          'http://archive.cloudera.com/debian/archive.key'
         end
         ```
 
-        Remove a repository from the list
+        **Remove a repository from the list**:
+
         ```ruby
         apt_repository 'zenoss' do
           action :remove
@@ -115,15 +122,15 @@ class Chef
         description: "The base of the Debian distribution."
 
       property :distribution, [ String, nil, FalseClass ],
-        description: "Usually a distribution's codename, such as xenial, bionic, or focal.",
+        description: "Usually a distribution's codename, such as `xenial`, `bionic`, or `focal`.",
         default: lazy { node["lsb"]["codename"] }, default_description: "The LSB codename of the node such as 'focal'."
 
       property :components, Array,
         description: "Package groupings, such as 'main' and 'stable'.",
-        default: lazy { [] }, default_description: "'main' if using a PPA repository."
+        default: lazy { [] }, default_description: "`main` if using a PPA repository."
 
       property :arch, [String, nil, FalseClass],
-        description: "Constrain packages to a particular CPU architecture such as 'i386' or 'amd64'."
+        description: "Constrain packages to a particular CPU architecture such as `i386` or `amd64`."
 
       property :trusted, [TrueClass, FalseClass],
         description: "Determines whether you should treat all packages from this repository as authenticated regardless of signature.",

data/lib/chef/resource/apt_update.rb

@@ -25,10 +25,11 @@ class Chef
 
       provides(:apt_update) { true }
 
-      description "Use the apt_update resource to manage APT repository updates on Debian and Ubuntu platforms."
+      description "Use the **apt_update** resource to manage APT repository updates on Debian and Ubuntu platforms."
       introduced "12.7"
       examples <<~DOC
-        Update the Apt repository at a specified interval
+        **Update the Apt repository at a specified interval**:
+
         ```ruby
         apt_update 'all platforms' do
         frequency 86400
@@ -36,7 +37,8 @@ class Chef
         end
         ```
 
-        Update the Apt repository at the start of a Chef Infra Client run
+        **Update the Apt repository at the start of a Chef Infra Client run**:
+
         ```ruby
         apt_update 'update'
         ```
@@ -46,7 +48,7 @@ class Chef
       property :name, String, default: ""
 
       property :frequency, Integer,
-        description: "Determines how frequently (in seconds) APT repository updates are made. Use this property when the :periodic action is specified.",
+        description: "Determines how frequently (in seconds) APT repository updates are made. Use this property when the `:periodic` action is specified.",
         default: 86_400
 
       default_action :periodic

data/lib/chef/resource/archive_file.rb

@@ -29,9 +29,10 @@ class Chef
       provides :libarchive_file # legacy cookbook name
 
       introduced "15.0"
-      description "Use the archive_file resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats."
+      description "Use the **archive_file** resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats."
       examples <<~DOC
-        Extract a zip file to a specified directory
+        **Extract a zip file to a specified directory**:
+
         ```ruby
         archive_file 'Precompiled.zip' do
           path '/tmp/Precompiled.zip'
@@ -60,11 +61,11 @@ class Chef
         required: true
 
       property :options, [Array, Symbol],
-        description: "An array of symbols representing extraction flags. Example: :no_overwrite to prevent overwriting files on disk. By default, this properly sets :time which preserves the modification timestamps of files in the archive when writing them to disk.",
+        description: "An array of symbols representing extraction flags. Example: `:no_overwrite` to prevent overwriting files on disk. By default, this properly sets `:time` which preserves the modification timestamps of files in the archive when writing them to disk.",
         default: lazy { [:time] }
 
       property :overwrite, [TrueClass, FalseClass, :auto],
-        description: "Should the resource overwrite the destination file contents if they already exist? If set to :auto the date stamp of files within the archive will be compared to those on disk and disk contents will be overwritten if they differ. This may cause unintended consequences if disk date stamps are changed between runs, which will result in the files being overwritten during each client run. Make sure to properly test any change to this property.",
+        description: "Should the resource overwrite the destination file contents if they already exist? If set to `:auto` the date stamp of files within the archive will be compared to those on disk and disk contents will be overwritten if they differ. This may cause unintended consequences if disk date stamps are changed between runs, which will result in the files being overwritten during each client run. Make sure to properly test any change to this property.",
         default: false
 
       # backwards compatibility for the legacy cookbook names

data/lib/chef/resource/bash.rb

@@ -26,7 +26,7 @@ class Chef
 
       provides :bash
 
-      description "Use the bash resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the execute resource. 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 **bash** resource to execute scripts using the Bash interpreter. This resource may also use any of the actions and properties that are available to the execute resource. 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

data/lib/chef/resource/batch.rb

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

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,22 +24,25 @@ 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"]

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,

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,7 +39,7 @@ 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