chef 13.6.4 → 13.7.16

data/lib/chef/resource/apt_package.rb

@@ -21,6 +21,7 @@ require "chef/provider/package/apt"
 
 class Chef
   class Resource
+    # Use the apt_package resource to manage packages on Debian and Ubuntu platforms.
     class AptPackage < Chef::Resource::Package
       resource_name :apt_package
       provides :package, os: "linux", platform_family: "debian"

data/lib/chef/resource/apt_preference.rb

@@ -20,6 +20,10 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # The apt_preference resource allows for the creation of APT preference files. Preference files are used to control
+    # which package versions and sources are prioritized during installation.
+    #
+    # @since 13.3
     class AptPreference < Chef::Resource
       resource_name :apt_preference
       provides :apt_preference

data/lib/chef/resource/apt_repository.rb

@@ -20,6 +20,10 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the apt_repository resource to specify additional APT repositories. Adding a new repository will update
+    # APT package cache immediately.
+    #
+    # @since 12.9
     class AptRepository < Chef::Resource
       resource_name :apt_repository
       provides :apt_repository

data/lib/chef/resource/apt_update.rb

@@ -20,6 +20,9 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the apt_update resource to manage APT repository updates on Debian and Ubuntu platforms.
+    #
+    # @since 12.7
     class AptUpdate < Chef::Resource
       resource_name :apt_update
       provides :apt_update

data/lib/chef/resource/bash.rb

@@ -21,6 +21,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # 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.
     class Bash < Chef::Resource::Script
 
       def initialize(name, run_context = nil)

data/lib/chef/resource/batch.rb

@@ -20,6 +20,11 @@ require "chef/resource/windows_script"
 
 class Chef
   class Resource
+    # 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.
     class Batch < Chef::Resource::WindowsScript
 
       provides :batch, os: "windows"

data/lib/chef/resource/bff_package.rb

@@ -21,6 +21,10 @@ require "chef/provider/package/aix"
 
 class Chef
   class Resource
+    # 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.
+    #
+    # @since 12.0
     class BffPackage < Chef::Resource::Package
     end
   end

data/lib/chef/resource/breakpoint.rb

@@ -20,6 +20,12 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the breakpoint resource to add breakpoints to recipes. Run the chef-shell in chef-client mode, and then use
+    # those breakpoints to debug recipes. Breakpoints are ignored by the chef-client during an actual chef-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.
+    #
+    # @since 12.0
     class Breakpoint < Chef::Resource
       provides :breakpoint
       resource_name :breakpoint

data/lib/chef/resource/cab_package.rb

@@ -21,24 +21,24 @@ require "chef/mixin/uris"
 
 class Chef
   class Resource
+    # Use the cab_package resource to install or remove Microsoft Windows cabinet (.cab) packages.
+    #
+    # @since 12.15
     class CabPackage < Chef::Resource::Package
       include Chef::Mixin::Uris
 
+      resource_name :cab_package
       provides :cab_package, os: "windows"
 
       allowed_actions :install, :remove
 
-      def initialize(name, run_context = nil)
-        super
-        @resource_name = :cab_package
-      end
-
       property  :source, String,
                 coerce: (proc do |s|
                   unless s.nil?
                     uri_scheme?(s) ? s : Chef::Util::PathHelper.canonical_path(s, false)
                   end
-                end)
+                end),
+                default: lazy { |r| r.package_name }
     end
   end
 end

data/lib/chef/resource/chef_gem.rb

@@ -21,6 +21,18 @@ require "chef/resource/gem_package"
 
 class Chef
   class Resource
+    # Use the chef_gem resource to install a gem only for the instance of Ruby that is dedicated to the chef-client.
+    # When a gem is installed from a local file, it must be added to the node using the remote_file or cookbook_file
+    # resources.
+    #
+    # The chef_gem resource works with all of the same properties and options as the gem_package resource, but does not
+    # accept the gem_binary property because it always uses the CurrentGemEnvironment under which the chef-client is
+    # running. In addition to performing actions similar to the gem_package resource, the chef_gem resource does the
+    # following:
+    #  - Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is
+    #    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
     class ChefGem < Chef::Resource::Package::GemPackage
       resource_name :chef_gem
 
@@ -30,6 +42,7 @@ class Chef
                }
       property :compile_time, [ true, false ], default: false, desired_state: false
 
+      # force the resource to compile time if the compile time property has been set
       def after_created
         if compile_time
           Array(action).each do |action|

data/lib/chef/resource/chocolatey_package.rb

@@ -20,22 +20,20 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the chocolatey_package resource to manage packages using Chocolatey on the Microsoft Windows platform.
+    #
+    # @since 12.7
     class ChocolateyPackage < Chef::Resource::Package
 
+      resource_name :chocolatey_package
       provides :chocolatey_package, os: "windows"
 
       allowed_actions :install, :upgrade, :remove, :uninstall, :purge, :reconfig
 
-      def initialize(name, run_context = nil)
-        super
-        @resource_name = :chocolatey_package
-      end
-
       # windows can't take Array options yet
       property :options, String
 
       property :package_name, [String, Array], coerce: proc { |x| [x].flatten }
-
       property :version, [String, Array], coerce: proc { |x| [x].flatten }
       property :returns, [Integer, Array], default: [ 0 ], desired_state: false
     end

data/lib/chef/resource/cookbook_file.rb

@@ -24,26 +24,24 @@ require "chef/mixin/securable"
 
 class Chef
   class Resource
+    # Use the cookbook_file resource to transfer files from a sub-directory of COOKBOOK_NAME/files/ to a specified path
+    # located on a host that is running the chef-client. The file is selected according to file specificity, which allows
+    # different source files to be used based on the hostname, host platform (operating system, distro, or as appropriate),
+    # or platform version. Files that are located in the COOKBOOK_NAME/files/default sub-directory may be used on any
+    # platform.
+    #
+    # During a chef-client run, the checksum for each local file is calculated and then compared against the checksum for
+    # the same file as it currently exists in the cookbook on the Chef server. A file is not transferred when the checksums
+    # match. Only files that require an update are transferred from the Chef server to a node.
     class CookbookFile < Chef::Resource::File
       include Chef::Mixin::Securable
 
-      default_action :create
-
-      def initialize(name, run_context = nil)
-        super
-        @provider = Chef::Provider::CookbookFile
-        @source = ::File.basename(name)
-        @cookbook = nil
-      end
+      resource_name :cookbook_file
 
-      def source(source_filename = nil)
-        set_or_return(:source, source_filename, :kind_of => [ String, Array ])
-      end
-
-      def cookbook(cookbook_name = nil)
-        set_or_return(:cookbook, cookbook_name, :kind_of => String)
-      end
+      property :source, [ String, Array ], default: lazy { ::File.basename(name) }
+      property :cookbook, String
 
+      default_action :create
     end
   end
 end

data/lib/chef/resource/cron.rb

@@ -21,6 +21,8 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # 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.
     class Cron < Chef::Resource
 
       identity_attr :command

data/lib/chef/resource/csh.rb

@@ -21,6 +21,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # Use the csh resource to execute scripts using the csh 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.
     class Csh < Chef::Resource::Script
 
       def initialize(name, run_context = nil)

data/lib/chef/resource/directory.rb

@@ -2,7 +2,7 @@
 # Author:: Adam Jacob (<adam@chef.io>)
 # Author:: Seth Chisamore (<schisamo@chef.io>)
 # Author:: Tyler Cloke (<tyler@chef.io>)
-# Copyright:: Copyright 2008-2016, Chef Software Inc.
+# Copyright:: Copyright 2008-2017, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -19,14 +19,16 @@
 #
 
 require "chef/resource"
-require "chef/provider/directory"
 require "chef/mixin/securable"
 
 class Chef
   class Resource
+    # Use the directory resource to manage a directory, which is a hierarchy of folders that comprises all of the
+    # information stored on a computer. The root directory is the top-level, under which the rest of the directory
+    # is organized. The directory resource uses the name property to specify the path to a location in a directory.
+    # Typically, permission to access that location in the directory is required.
     class Directory < Chef::Resource
-
-      identity_attr :path
+      resource_name :directory
 
       state_attrs :group, :mode, :owner
 
@@ -35,28 +37,8 @@ class Chef
       default_action :create
       allowed_actions :create, :delete
 
-      def initialize(name, run_context = nil)
-        super
-        @path = name
-        @recursive = false
-      end
-
-      def recursive(arg = nil)
-        set_or_return(
-          :recursive,
-          arg,
-          :kind_of => [ TrueClass, FalseClass ]
-        )
-      end
-
-      def path(arg = nil)
-        set_or_return(
-          :path,
-          arg,
-          :kind_of => String
-        )
-      end
-
+      property :path, String, name_property: true, identity: true
+      property :recursive, [ TrueClass, FalseClass ], default: false
     end
   end
 end

data/lib/chef/resource/dnf_package.rb

@@ -21,6 +21,11 @@ require "chef/mixin/shell_out"
 
 class Chef
   class Resource
+    # Use the dnf_package resource to install, upgrade, and remove packages with DNF for Fedora platforms. The dnf_package
+    # resource is able to resolve provides data for packages much like DNF can do when it is run from the command line.
+    # This allows a variety of options for installing packages, like minimum versions, virtual provides, and library names.
+    #
+    # @since 12.18
     class DnfPackage < Chef::Resource::Package
       extend Chef::Mixin::Which
       extend Chef::Mixin::ShellOut

data/lib/chef/resource/dpkg_package.rb

@@ -20,6 +20,8 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the dpkg_package resource to manage packages for the dpkg platform. When a package is installed from a local
+    # file, it must be added to the node using the remote_file or cookbook_file resources.
     class DpkgPackage < Chef::Resource::Package
       resource_name :dpkg_package
       provides :dpkg_package, os: "linux"

data/lib/chef/resource/dsc_resource.rb

@@ -19,6 +19,11 @@ require "chef/dsl/powershell"
 
 class Chef
   class Resource
+    # The dsc_resource resource allows any DSC resource to be used in a Chef recipe, as well as any custom resources
+    # that have been added to your Windows PowerShell environment. Microsoft frequently adds new resources to the DSC
+    # resource collection.
+    #
+    # @since 12.2
     class DscResource < Chef::Resource
       provides :dsc_resource, os: "windows"
 

data/lib/chef/resource/dsc_script.rb

@@ -21,9 +21,15 @@ require "chef/dsl/powershell"
 
 class Chef
   class Resource
+    # Many DSC resources are comparable to built-in Chef resources. For example, both DSC and Chef have file, package,
+    # and service resources. The dsc_script resource is most useful for those DSC resources that do not have a direct
+    # comparison to a resource in Chef, such as the Archive resource, a custom DSC resource, an existing DSC script
+    # that performs an important task, and so on. Use the dsc_script resource to embed the code that defines a DSC
+    # configuration directly within a Chef recipe.
     class DscScript < Chef::Resource
       include Chef::DSL::Powershell
 
+      resource_name :dsc_script
       provides :dsc_script, os: "windows"
 
       default_action :run

data/lib/chef/resource/env.rb

@@ -19,7 +19,10 @@
 
 class Chef
   class Resource
+    # Use the env resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft
+    # Windows must be restarted before the environment key will be available to the Task Scheduler.
     class Env < Chef::Resource
+      resource_name :env
       provides :env, os: "windows"
 
       default_action :create

data/lib/chef/resource/erl_call.rb

@@ -80,6 +80,11 @@ class Chef
         )
       end
 
+      # This resource is deprecated.
+      def after_created
+        Chef.deprecated(:erl_resource, "The #{resource_name} resource (#{source_line}) is deprecated and will be removed from Chef core in 14.0 (April 2018).")
+      end
+
     end
   end
 end

data/lib/chef/resource/execute.rb

@@ -22,6 +22,9 @@ require "chef/provider/execute"
 
 class Chef
   class Resource
+    # Use the execute resource to execute a single command. 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.
     class Execute < Chef::Resource
 
       identity_attr :command
@@ -130,7 +133,8 @@ class Chef
 
       property :password, String, sensitive: true
 
-      property :sensitive, [ TrueClass, FalseClass ], default: false, coerce: proc { |x| password ? true : x }
+      # lazy used to set default value of sensitive to true if password is set
+      property :sensitive, [ TrueClass, FalseClass ], default: lazy { |r| r.password ? true : false }
 
       property :elevated, [ TrueClass, FalseClass ], default: false
 

data/lib/chef/resource/file.rb

@@ -25,6 +25,7 @@ require "pathname"
 
 class Chef
   class Resource
+    # Use the file resource to manage files directly on a node.
     class File < Chef::Resource
       include Chef::Mixin::Securable
 
@@ -43,7 +44,7 @@ class Chef
       # mutate the new_resource.checksum which would change the
       # user intent in the new_resource if the resource is reused.
       #
-      # @returns [String] Checksum of the file we actually rendered
+      # @return [String] Checksum of the file we actually rendered
       attr_accessor :final_checksum
 
       default_action :create

data/lib/chef/resource/file/verification.rb

@@ -119,6 +119,16 @@ class Chef
           v = verification_class.new(@parent_resource, @command, @command_opts, &@block)
           v.verify(path, opts)
         end
+
+        def to_s
+          if @block
+            "<Proc>"
+          elsif @command.is_a?(Symbol)
+            "#{@command.inspect} (#{Chef::Resource::File::Verification.lookup(@command).name})"
+          elsif @command.is_a?(String)
+            @command
+          end
+        end
       end
     end
   end

data/lib/chef/resource/freebsd_package.rb

@@ -26,25 +26,33 @@ require "chef/mixin/shell_out"
 
 class Chef
   class Resource
+    # Use the freebsd_package resource to manage packages for the FreeBSD platform.
     class FreebsdPackage < Chef::Resource::Package
       include Chef::Mixin::ShellOut
 
       resource_name :freebsd_package
       provides :package, platform: "freebsd"
 
+      # make sure we assign the appropriate underlying providers based on what
+      # package managers exist on this FreeBSD system or the source of the package
+      #
+      # @return [void]
       def after_created
         assign_provider
       end
 
+      # Is the system at least version 1000017 or is the make variable WITH_PKGNG set
+      #
+      # @return [Boolean] do we support pkgng
       def supports_pkgng?
         ships_with_pkgng? || !!shell_out_compact!("make", "-V", "WITH_PKGNG", :env => nil).stdout.match(/yes/i)
       end
 
       private
 
+      # It was not until __FreeBSD_version 1000017 that pkgng became
+      # the default binary package manager. See '/usr/ports/Mk/bsd.port.mk'.
       def ships_with_pkgng?
-        # It was not until __FreeBSD_version 1000017 that pkgng became
-        # the default binary package manager. See '/usr/ports/Mk/bsd.port.mk'.
         node[:os_version].to_i >= 1000017
       end