chef 17.6.18-universal-mingw32 → 17.9.18-universal-mingw32

data/lib/chef/provider/package/yum.rb

@@ -36,6 +36,7 @@ class Chef
         allow_nils
         use_multipackage_api
         use_package_name_for_source
+        use_magic_version
 
         provides :package, platform_family: "fedora_derived"
 
@@ -64,6 +65,16 @@ class Chef
           current_resource
         end
 
+        def load_after_resource
+          # force the installed version array to repopulate
+          @current_version = []
+          @after_resource = Chef::Resource::YumPackage.new(new_resource.name)
+          after_resource.package_name(new_resource.package_name)
+          after_resource.version(get_current_versions)
+
+          after_resource
+        end
+
         def define_resource_requirements
           requirements.assert(:install, :upgrade, :remove, :purge) do |a|
             a.assertion { !new_resource.source || ::File.exist?(new_resource.source) }
@@ -80,9 +91,15 @@ class Chef
           end
         end
 
+        def magic_version_array
+          package_name_array.each_with_index.map do |pkg, i|
+            magical_version(i).version_with_arch
+          end
+        end
+
         def get_current_versions
           package_name_array.each_with_index.map do |pkg, i|
-            installed_version(i).version_with_arch
+            current_version(i).version_with_arch
           end
         end
 
@@ -127,7 +144,7 @@ class Chef
         alias upgrade_package install_package
 
         def remove_package(names, versions)
-          resolved_names = names.each_with_index.map { |name, i| installed_version(i).to_s unless name.nil? }
+          resolved_names = names.each_with_index.map { |name, i| magical_version(i).to_s unless name.nil? }
           yum(options, "-y", "remove", resolved_names)
           flushcache
         end
@@ -157,10 +174,10 @@ class Chef
         def resolved_package_lock_names(names)
           names.each_with_index.map do |name, i|
             unless name.nil?
-              if installed_version(i).version.nil?
+              if magical_version(i).version.nil?
                 available_version(i).name
               else
-                installed_version(i).name
+                magical_version(i).name
               end
             end
           end
@@ -226,15 +243,25 @@ class Chef
           @available_version[index]
         end
 
+        def magical_version(index)
+          @magical_version ||= []
+          @magical_version[index] ||= if new_resource.source
+                                        python_helper.package_query(:whatinstalled, available_version(index).name, version: safe_version_array[index], arch: safe_arch_array[index], options: options)
+                                      else
+                                        python_helper.package_query(:whatinstalled, package_name_array[index], version: safe_version_array[index], arch: safe_arch_array[index], options: options)
+                                      end
+          @magical_version[index]
+        end
+
         # @return Array<Version>
-        def installed_version(index)
-          @installed_version ||= []
-          @installed_version[index] ||= if new_resource.source
-                                          python_helper.package_query(:whatinstalled, available_version(index).name, arch: safe_arch_array[index], options: options)
-                                        else
-                                          python_helper.package_query(:whatinstalled, package_name_array[index], arch: safe_arch_array[index], options: options)
-                                        end
-          @installed_version[index]
+        def current_version(index)
+          @current_version ||= []
+          @current_version[index] ||= if new_resource.source
+                                        python_helper.package_query(:whatinstalled, available_version(index).name, arch: safe_arch_array[index], options: options)
+                                      else
+                                        python_helper.package_query(:whatinstalled, package_name_array[index], arch: safe_arch_array[index], options: options)
+                                      end
+          @current_version[index]
         end
 
         def flushcache

data/lib/chef/provider/package/zypper.rb

@@ -113,6 +113,8 @@ class Chef
             end
           end
           nil
+        rescue
+          nil
         end
 
         def available_version(index)

data/lib/chef/provider/package.rb

@@ -107,7 +107,7 @@ class Chef
         end
       end
 
-      action :install do
+      action :install, description: "Install a package. If a version is specified, install the specified version of the package." do
         unless target_version_array.any?
           logger.debug("#{new_resource} is already installed - nothing to do")
           return
@@ -136,7 +136,7 @@ class Chef
 
       private :install_description
 
-      action :upgrade do
+      action :upgrade, description: "Install a package and ensure that a package is the latest version." do
         unless target_version_array.any?
           logger.debug("#{new_resource} no versions to upgrade - nothing to do")
           return
@@ -167,7 +167,7 @@ class Chef
 
       private :upgrade_description
 
-      action :remove do
+      action :remove, description: "Remove a package." do
         if removing_package?
           description = new_resource.version ? "version #{new_resource.version} of " : ""
           converge_by("remove #{description}package #{current_resource.package_name}") do
@@ -202,7 +202,7 @@ class Chef
         end
       end
 
-      action :purge do
+      action :purge, description: "Purge a package. This action typically removes the configuration files as well as the package." do
         if removing_package?
           description = new_resource.version ? "version #{new_resource.version} of" : ""
           converge_by("purge #{description} package #{current_resource.package_name}") do
@@ -438,47 +438,81 @@ class Chef
         @target_version_array ||=
           begin
             target_version_array = []
-            each_package do |package_name, new_version, current_version, candidate_version|
+            each_package do |package_name, new_version, current_version, candidate_version, magic_version|
               case action
               when :upgrade
-                if current_version.nil?
-                  # with use_magic_version there may be a package installed, but it fails the user's
-                  # requested new_resource.version constraints
+                if version_equals?(current_version, new_version)
+                  # This is a short-circuit (mostly for the rubygems provider) to avoid needing to
+                  # expensively query the candidate_version which must come later.  This only checks
+                  # exact matching, the check for fuzzy matching is later.
+                  logger.trace("#{new_resource} #{package_name} #{new_version} is already installed")
+                  target_version_array.push(nil)
+                elsif current_version.nil?
+                  # This is a simple check to see if we have any currently installed version at all, this is
+                  # safe to do before the allow_downgrade check so we check this before.
                   logger.trace("#{new_resource} has no existing installed version. Installing install #{candidate_version}")
                   target_version_array.push(candidate_version)
-                elsif !use_magic_version? && version_equals?(current_version, new_version)
-                  # this is a short-circuit (mostly for the rubygems provider) to avoid needing to expensively query the candidate_version which must come later
-                  logger.trace("#{new_resource} #{package_name} #{new_version} is already installed")
+                elsif !allow_downgrade && version_compare(current_version, candidate_version) == 1
+                  # This check for downgrading when allow_downgrade is false uses the current_version rather
+                  # than the magic_version since we never want to downgrade even if the constraints are not met
+                  # if the version is higher.  This check does use the candidate_version and unlazies this so
+                  # there will a perf hit on idempotent use when allow_downgrade is false which is unavoidable.
+                  logger.trace("#{new_resource} #{package_name} has installed version #{current_version}, which is newer than available version #{candidate_version}. Skipping...)")
                   target_version_array.push(nil)
+                elsif magic_version.nil?
+                  # This is the check for fuzzy matching of the installed_version, where if the installed version
+                  # does not match the desired version constraints (but is not an exact match) then we need to
+                  # install the candidate_version (this must come after the allow_downgrade check)
+                  logger.trace("#{new_resource} has an installed version that does not match the version constraint. Installing install #{candidate_version}")
+                  target_version_array.push(candidate_version)
                 elsif candidate_version.nil?
+                  # This check necessarily unlazies the candidate_version and may be expensive (connecting to
+                  # rubygems.org or whatever).  It comes as late as possible.
                   logger.trace("#{new_resource} #{package_name} has no candidate_version to upgrade to")
                   target_version_array.push(nil)
                 elsif version_equals?(current_version, candidate_version)
+                  # This check sees if the candidate_version is already installed or if we should upgrade/update the
+                  # package.  This is the normal idempotent behavior of :upgrade and is inherently expensive due to
+                  # unlazying the candidate_version.  To prevent the perf hit the version may be specified with a full
+                  # version constraint.  Then the cookbook can roll the version forward and use :upgrade to force version
+                  # pinning.
                   logger.trace("#{new_resource} #{package_name} #{candidate_version} is already installed")
                   target_version_array.push(nil)
-                elsif !allow_downgrade && version_compare(current_version, candidate_version) == 1
-                  logger.trace("#{new_resource} #{package_name} has installed version #{current_version}, which is newer than available version #{candidate_version}. Skipping...)")
-                  target_version_array.push(nil)
                 else
-                  logger.trace("#{new_resource} #{package_name} is out of date, will upgrade to #{candidate_version}")
+                  logger.trace("#{new_resource} #{package_name} is out of date, will update to #{candidate_version}")
                   target_version_array.push(candidate_version)
                 end
 
               when :install
-                if new_version && !use_magic_version?
+                if current_version && new_version && !allow_downgrade && version_compare(current_version, new_version) == 1
+                  # This is the idempotency guard for downgrades when downgrades are not allowed.  This should perhaps raise
+                  # an exception since we were told to install an exact package version but we are silently refusing to do so
+                  # because a higher version is already installed.  Maybe we need a flag for users to apply their preferred
+                  # declarative philosophy?  This has to come early and outside of the two code paths below.
+                  logger.warn("#{new_resource} #{package_name} has installed version #{current_version}, which is newer than available version #{new_version}. Skipping...)")
+                  target_version_array.push(nil)
+                elsif new_version && !use_magic_version?
+                  # This is for "non magic version using" subclasses to do comparisons between the current_version and the
+                  # desired new_version.  XXX: If we converted this to current_version_requirement_satisfied? and made it specific
+                  # to the current version check and then eliminated the magic_version, we might be able to eliminate separate codepaths
+                  # here, and eliminate the semantic confusion around the magic_version?
                   if version_requirement_satisfied?(current_version, new_version)
                     logger.trace("#{new_resource} #{package_name} #{current_version} satisfies #{new_version} requirement")
                     target_version_array.push(nil)
-                  elsif current_version && !allow_downgrade && version_compare(current_version, new_version) == 1
-                    logger.warn("#{new_resource} #{package_name} has installed version #{current_version}, which is newer than available version #{new_version}. Skipping...)")
-                    target_version_array.push(nil)
                   else
+                    # XXX: some subclasses seem to depend on this behavior where the new_version can be different from the
+                    # candidate_version and we install the new_version, it seems like the candidate_version should be fixed to
+                    # be resolved correctly to the new_version for those providers.  although it may just be unit test bugs.
+                    # it would be more correct to use the candidate_version here, but then it needs to be the correctly resolved
+                    # candidate_version against the new_version constraint.
                     logger.trace("#{new_resource} #{package_name} #{current_version} needs updating to #{new_version}")
                     target_version_array.push(new_version)
                   end
-                elsif current_version.nil?
-                  # with use_magic_version there may be a package installed, but it fails the user's
-                  # requested new_resource.version constraints
+                elsif magic_version.nil?
+                  # This is for when we have a "magic version using" subclass and where the installed version does not match the
+                  # constraint specified in the new_version, so we need to upgrade to the candidate_version.  This is the only
+                  # codepath in the :install branch which references the candidate_version so it is slow, but it is the path where
+                  # we need to do work anyway.  XXX: should we check for candidate_version.nil? somewhere around here?
                   logger.trace("#{new_resource} #{package_name} not installed, installing #{candidate_version}")
                   target_version_array.push(candidate_version)
                 else
@@ -512,8 +546,8 @@ class Chef
         @packages_missing_candidates ||=
           begin
             missing = []
-            each_package do |package_name, new_version, current_version, candidate_version|
-              missing.push(package_name) if current_version.nil? && candidate_version.nil?
+            each_package do |package_name, new_version, current_version, candidate_version, magic_version|
+              missing.push(package_name) if magic_version.nil? && candidate_version.nil?
             end
             missing
           end
@@ -536,7 +570,7 @@ class Chef
         @forced_packages_missing_candidates ||=
           begin
             missing = []
-            each_package do |package_name, new_version, current_version, candidate_version|
+            each_package do |package_name, new_version, current_version, candidate_version, magic_version|
               next if new_version.nil? || current_version.nil?
 
               if use_magic_version?
@@ -559,9 +593,10 @@ class Chef
       def each_package
         package_name_array.each_with_index do |package_name, i|
           candidate_version = candidate_version_array[i]
-          current_version = use_magic_version? ? magic_version[i] : current_version_array[i]
+          current_version = current_version_array[i]
+          magic_version = use_magic_version? ? magic_version_array[i] : current_version_array[i]
           new_version = new_version_array[i]
-          yield package_name, new_version, current_version, candidate_version
+          yield package_name, new_version, current_version, candidate_version, magic_version
         end
       end
 

data/lib/chef/provider/subversion.rb

@@ -58,7 +58,7 @@ class Chef
       action :checkout, description: "Clone or check out the source. When a checkout is available, this provider does nothing." do
         if target_dir_non_existent_or_empty?
           converge_by("perform checkout of #{new_resource.repository} into #{new_resource.destination}") do
-            shell_out!(checkout_command, run_options)
+            shell_out!(checkout_command, **run_options)
           end
         else
           logger.debug "#{new_resource} checkout destination #{new_resource.destination} already exists or is a non-empty directory - nothing to do"
@@ -75,7 +75,7 @@ class Chef
 
       action :force_export, description: "Export the source, excluding or removing any version control artifacts and force an export of the source that is overwriting the existing copy (if it exists)." do
         converge_by("export #{new_resource.repository} into #{new_resource.destination}") do
-          shell_out!(export_command, run_options)
+          shell_out!(export_command, **run_options)
         end
       end
 
@@ -86,7 +86,7 @@ class Chef
           logger.trace "#{new_resource} current revision: #{current_rev} target revision: #{revision_int}"
           unless current_revision_matches_target_revision?
             converge_by("sync #{new_resource.destination} from #{new_resource.repository}") do
-              shell_out!(sync_command, run_options)
+              shell_out!(sync_command, **run_options)
               logger.info "#{new_resource} updated to revision: #{revision_int}"
             end
           end
@@ -125,7 +125,7 @@ class Chef
                             new_resource.revision
                           else
                             command = scm(:info, new_resource.repository, new_resource.svn_info_args, authentication, "-r#{new_resource.revision}")
-                            svn_info = shell_out!(command, run_options(cwd: cwd, returns: [0, 1])).stdout
+                            svn_info = shell_out!(command, **run_options(cwd: cwd, returns: [0, 1])).stdout
 
                             extract_revision_info(svn_info)
                           end
@@ -137,7 +137,7 @@ class Chef
         return nil unless ::File.exist?(::File.join(new_resource.destination, ".svn"))
 
         command = scm(:info)
-        svn_info = shell_out!(command, run_options(cwd: cwd, returns: [0, 1])).stdout
+        svn_info = shell_out!(command, **run_options(cwd: cwd, returns: [0, 1])).stdout
 
         extract_revision_info(svn_info)
       end

data/lib/chef/provider.rb

@@ -35,7 +35,6 @@ class Chef
     attr_accessor :after_resource
     attr_accessor :run_context
 
-    attr_reader :recipe_name
     attr_reader :logger
 
     include Chef::Mixin::WhyRun
@@ -174,6 +173,10 @@ class Chef
       new_resource.cookbook_name
     end
 
+    def recipe_name
+      new_resource.recipe_name
+    end
+
     # hook that subclasses can use to do lazy validation for where properties aren't flexible enough
     def check_resource_semantics!; end
 
@@ -269,7 +272,7 @@ class Chef
     end
 
     def requirements
-      @requirements ||= ResourceRequirements.new(@new_resource, run_context)
+      @requirements ||= ResourceRequirements.new(@new_resource, run_context, action || new_resource.action)
     end
 
     def description(description = "NOT_PASSED")

data/lib/chef/providers.rb

@@ -108,7 +108,6 @@ require_relative "provider/group/groupadd"
 require_relative "provider/group/groupmod"
 require_relative "provider/group/pw"
 require_relative "provider/group/solaris"
-require_relative "provider/group/suse"
 require_relative "provider/group/usermod"
 require_relative "provider/group/windows"
 

data/lib/chef/pwsh.rb

@@ -24,15 +24,16 @@ class Chef
     # bindir directory.
     #
     # @param script [String] script to run
+    # @param timeout [Integer, nil] timeout in seconds.
     # @return [Object] output
-    def initialize(script)
+    def initialize(script, timeout: -1)
       @dll = Pwsh.dll
       super
     end
 
     protected
 
-    def exec(script)
+    def exec(script, timeout: -1)
       # Note that we need to override the location of the shared dotnet core library
       # location. With most .net core applications, you can simply publish them as a
       # "self-contained" application allowing consumers of the application to run them

data/lib/chef/resource/apt_package.rb

@@ -43,7 +43,7 @@ class Chef
       **Install multiple packages at once**:
 
       ```ruby
-      apt_package %(package1 package2 package3)
+      apt_package %w(package1 package2 package3)
       ```
 
       **Install without using recommend packages as a dependency**:
@@ -55,7 +55,7 @@ class Chef
       ```
       DOC
 
-      description "Use the **apt_package** resource to manage packages on Debian and Ubuntu platforms."
+      description "Use the **apt_package** resource to manage packages on Debian, Ubuntu, and other platforms that use the APT package system."
 
       property :default_release, String,
         description: "The default release. For example: `stable`.",

data/lib/chef/resource/chef_client_config.rb

@@ -87,6 +87,16 @@ class Chef
         ]
       end
       ```
+
+      **Report directly to the [Chef Automate data collector endpoint](/automate/data_collection/#configure-chef-infra-client-to-use-the-data-collector-endpoint-in-chef-automate).**
+
+      ```ruby
+      chef_client_config 'Create client.rb' do
+        chef_server_url 'https://chef.example.dmz'
+        data_collector_server_url 'https://automate.example.dmz'
+        data_collector_token 'TEST_TOKEN_TEST'
+      end
+      ```
       DOC
 
       # @todo policy_file or policy_group being set requires the other to be set so enforce that.
@@ -231,6 +241,14 @@ 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"
 
+      property :data_collector_server_url, String,
+        description: "The data collector URL (typically automate) to send node, converge, and compliance data. Note: If possible, use Chef Infra Server to do all data collection reporting, as this removes the need to distribute tokens to individual nodes.",
+        introduced: "17.8"
+
+      property :data_collector_token, String,
+        description: "The data collector token to interact with the data collector server URL (Automate). Note: If possible, use Chef Infra Server to do all data collection reporting, as this removes the need to distribute tokens to individual nodes.",
+        introduced: "17.8"
+
       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
@@ -282,7 +300,9 @@ class Chef
             ssl_verify_mode: new_resource.ssl_verify_mode,
             start_handlers: format_handler(new_resource.start_handlers),
             additional_config: new_resource.additional_config,
-            policy_persist_run_list: new_resource.policy_persist_run_list
+            policy_persist_run_list: new_resource.policy_persist_run_list,
+            data_collector_server_url: new_resource.data_collector_server_url,
+            data_collector_token: new_resource.data_collector_token
           )
           mode "0640"
           action :create

data/lib/chef/resource/chef_client_launchd.rb

@@ -134,7 +134,7 @@ class Chef
           standard_error_path ::File.join(new_resource.log_directory, new_resource.log_file_name)
           program_arguments ["/bin/bash",
                              "-c",
-                             "echo; echo #{ChefUtils::Dist::Infra::PRODUCT} launchd daemon config has been updated. Manually unloading and reloading the daemon; echo Now unloading the daemon; /bin/launchctl unload /Library/LaunchDaemons/com.#{ChefUtils::Dist::Infra::SHORT}.#{ChefUtils::Dist::Infra::CLIENT}.plist; sleep 2; echo Now loading the daemon; /bin/launchctl load /Library/LaunchDaemons/com.#{ChefUtils::Dist::Infra::SHORT}.#{ChefUtils::Dist::Infra::CLIENT}.plist"]
+                             "echo; echo #{ChefUtils::Dist::Infra::PRODUCT} launchd daemon config has been updated. Manually unloading and reloading the daemon; echo Now unloading the daemon; sudo /bin/launchctl unload /Library/LaunchDaemons/com.#{ChefUtils::Dist::Infra::SHORT}.#{ChefUtils::Dist::Infra::CLIENT}.plist; sleep 2; echo Now loading the daemon; sudo /bin/launchctl load /Library/LaunchDaemons/com.#{ChefUtils::Dist::Infra::SHORT}.#{ChefUtils::Dist::Infra::CLIENT}.plist"]
           action :enable # enable creates the plist & triggers service restarts on change
         end
 

data/lib/chef/resource/chef_client_trusted_certificate.rb

@@ -75,6 +75,7 @@ class Chef
         file cert_path do
           content new_resource.certificate
           mode "0640"
+          sensitive new_resource.sensitive
         end
       end
 

data/lib/chef/resource/chocolatey_config.rb

@@ -21,7 +21,7 @@ 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. 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 "14.3"
       examples <<~DOC
       **Set the Chocolatey cacheLocation config**:

data/lib/chef/resource/chocolatey_feature.rb

@@ -20,7 +20,7 @@ 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. 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 "15.1"
       examples <<~DOC
         **Enable the checksumFiles Chocolatey feature**

data/lib/chef/resource/chocolatey_package.rb

@@ -25,7 +25,7 @@ class Chef
 
       provides :chocolatey_package
 
-      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."
+      description "Use the **chocolatey_package** resource to manage packages using the Chocolatey package manager 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. Warning: The **chocolatey_package** resource must be specified as `chocolatey_package` and cannot be shortened to `package` in a recipe."
       introduced "12.7"
       examples <<~DOC
         **Install a Chocolatey package**:
@@ -73,9 +73,9 @@ class Chef
         coerce: proc { |x| [x].flatten }
 
       # In the choco if we have the feature useEnhancedExitCodes turned on, then choco will provide enhanced exit codes(2: no results).
-      # Choco exit codes https://chocolatey.org/docs/commandsinfo#exit-codes
+      # Choco exit codes https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes
       property :returns, [Integer, Array],
-        description: "The exit code(s) returned a chocolatey package that indicate success.",
+        description: "The exit code(s) returned by the `choco` command that indicate a successful action. See [Chocolatey Exit Codes](https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes) for a complete list of exit codes used by Chocolatey.",
         default: [ 0, 2 ], desired_state: false,
         introduced: "12.18"
     end

data/lib/chef/resource/chocolatey_source.rb

@@ -20,7 +20,7 @@ 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. 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 "14.3"
       examples <<~DOC
         **Add a Chocolatey source**
@@ -63,6 +63,22 @@ class Chef
 
       property :disabled, [TrueClass, FalseClass], default: false, desired_state: false, skip_docs: true
 
+      property :username, String,
+               description: "The username to use when authenticating against the source",
+               introduced: "17.7"
+
+      property :password, String, sensitive: true, desired_state: false,
+               description: "The password to use when authenticating against the source",
+               introduced: "17.7"
+
+      property :cert, String,
+               description: "The certificate to use when authenticating against the source",
+               introduced: "17.7"
+
+      property :cert_password, String, sensitive: true, desired_state: false,
+               description: "The password for the certificate to use when authenticating against the source",
+               introduced: "17.7"
+
       load_current_value do
         element = fetch_source_element(source_name)
         current_value_does_not_exist! if element.nil?
@@ -74,6 +90,8 @@ class Chef
         allow_self_service element["selfService"] == "true"
         priority element["priority"].to_i
         disabled element["disabled"] == "true"
+        username element["user"]
+        cert element["certificate"]
       end
 
       # @param [String] id the source name
@@ -129,10 +147,14 @@ class Chef
         def choco_cmd(action)
           cmd = "#{ENV["ALLUSERSPROFILE"]}\\chocolatey\\bin\\choco source #{action} -n \"#{new_resource.source_name}\""
           if action == "add"
-            cmd << " -s #{new_resource.source} --priority=#{new_resource.priority}"
+            cmd << " --source=\"#{new_resource.source}\" --priority=#{new_resource.priority}"
             cmd << " --bypassproxy" if new_resource.bypass_proxy
             cmd << " --allowselfservice" if new_resource.allow_self_service
             cmd << " --adminonly" if new_resource.admin_only
+            cmd << " --user=\"#{new_resource.username}\"" if new_resource.username
+            cmd << " --password=\"#{new_resource.password}\"" if new_resource.password
+            cmd << " --cert=\"#{new_resource.cert}\"" if new_resource.cert
+            cmd << " --certpassword=\"#{new_resource.cert_password}\"" if new_resource.cert_password
           end
           cmd
         end

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

@@ -20,6 +20,7 @@
 require_relative "../../resource"
 require_relative "../helpers/cron_validations"
 require_relative "../../provider/cron" # do not remove. we actually need this below
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Resource
@@ -30,7 +31,80 @@ class Chef
 
       provides :cron
 
-      description "Use the **cron** resource to manage cron entries for time-based job scheduling. Properties for a schedule will default to * if not provided. The cron resource requires access to a crontab program, typically cron."
+      description "Use the **cron** resource to manage cron entries for time-based job scheduling. Properties for a schedule will default to * if not provided. The cron resource requires access to a crontab program, typically cron. Warning: The cron resource should only be used to modify an entry in a crontab file. The `cron_d` resource directly manages `cron.d` files. This resource ships in #{ChefUtils::Dist::Infra::PRODUCT} 14.4 or later and can also be found in the [cron](https://github.com/chef-cookbooks/cron) cookbook) for previous #{ChefUtils::Dist::Infra::PRODUCT} releases."
+
+      examples <<~'DOC'
+      **Run a program at a specified interval**
+
+      ```ruby
+      cron 'noop' do
+        hour '5'
+        minute '0'
+        command '/bin/true'
+      end
+      ```
+
+      **Run an entry if a folder exists**
+
+      ```ruby
+      cron 'ganglia_tomcat_thread_max' do
+        command "/usr/bin/gmetric
+          -n 'tomcat threads max'
+          -t uint32
+          -v '/usr/local/bin/tomcat-stat --thread-max'"
+        only_if { ::File.exist?('/home/jboss') }
+      end
+      ```
+
+      **Run every Saturday, 8:00 AM**
+
+      The following example shows a schedule that will run every hour at 8:00 each Saturday morning, and will then send an email to “admin@example.com” after each run.
+
+      ```ruby
+      cron 'name_of_cron_entry' do
+        minute '0'
+        hour '8'
+        weekday '6'
+        mailto 'admin@example.com'
+        action :create
+      end
+      ```
+
+      **Run once a week**
+
+      ```ruby
+      cron 'cookbooks_report' do
+        minute '0'
+        hour '0'
+        weekday '1'
+        user 'chefio'
+        mailto 'sysadmin@example.com'
+        home '/srv/supermarket/shared/system'
+        command %W{
+          cd /srv/supermarket/current &&
+          env RUBYLIB="/srv/supermarket/current/lib"
+          RAILS_ASSET_ID=`git rev-parse HEAD` RAILS_ENV="#{rails_env}"
+          bundle exec rake cookbooks_report
+        }.join(' ')
+        action :create
+      end
+      ```
+
+      **Run only in November**
+
+      The following example shows a schedule that will run at 8:00 PM, every weekday (Monday through Friday), but only in November:
+
+      ```ruby
+      cron 'name_of_cron_entry' do
+        minute '0'
+        hour '20'
+        day '*'
+        month '11'
+        weekday '1-5'
+        action :create
+      end
+      ```
+      DOC
 
       state_attrs :minute, :hour, :day, :month, :weekday, :user