chef 13.6.4 → 13.7.16

data/lib/chef/resource/openbsd_package.rb

@@ -25,6 +25,9 @@ require "chef/mixin/shell_out"
 
 class Chef
   class Resource
+    # Use the openbsd_package resource to manage packages for the OpenBSD platform.
+    #
+    # @since 12.1
     class OpenbsdPackage < Chef::Resource::Package
       include Chef::Mixin::ShellOut
 

data/lib/chef/resource/osx_profile.rb

@@ -20,6 +20,12 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the osx_profile resource to manage configuration profiles (.mobileconfig files)
+    # on the macOS platform. The osx_profile resource installs profiles by using
+    # the uuidgen library to generate a unique ProfileUUID, and then using the
+    # profiles command to install the profile on the system.
+    #
+    # @since 12.7
     class OsxProfile < Chef::Resource
       provides :osx_profile, os: "darwin"
       provides :osx_config_profile, os: "darwin"
@@ -29,46 +35,10 @@ class Chef
       default_action :install
       allowed_actions :install, :remove
 
-      def initialize(name, run_context = nil)
-        super
-        @profile_name = name
-        @profile = nil
-        @identifier = nil
-        @path = nil
-      end
-
-      def profile_name(arg = nil)
-        set_or_return(
-          :profile_name,
-          arg,
-          :kind_of => [ String ]
-        )
-      end
-
-      def profile(arg = nil)
-        set_or_return(
-          :profile,
-          arg,
-          :kind_of => [ String, Hash ]
-        )
-      end
-
-      def identifier(arg = nil)
-        set_or_return(
-          :identifier,
-          arg,
-          :kind_of => [ String ]
-        )
-      end
-
-      def path(arg = nil)
-        set_or_return(
-          :path,
-          arg,
-          :kind_of => [ String ]
-        )
-      end
-
+      property :profile_name, String, name_property: true
+      property :profile, [ String, Hash ]
+      property :identifier, String
+      property :path, String
     end
   end
 end

data/lib/chef/resource/package.rb

@@ -21,6 +21,12 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the package resource to manage packages. When the package is installed from a local file (such as with RubyGems,
+    # dpkg, or RPM Package Manager), the file must be added to the node using the remote_file or cookbook_file resources.
+    #
+    # This resource is the base resource for several other resources used for package management on specific platforms.
+    # While it is possible to use each of these specific resources, it is recommended to use the package resource as often
+    # as possible.
     class Package < Chef::Resource
       resource_name :package
 

data/lib/chef/resource/pacman_package.rb

@@ -20,6 +20,7 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the pacman_package resource to manage packages (using pacman) on the Arch Linux platform.
     class PacmanPackage < Chef::Resource::Package
       resource_name :pacman_package
       provides :pacman_package, os: "linux"

data/lib/chef/resource/paludis_package.rb

@@ -21,6 +21,9 @@ require "chef/provider/package/paludis"
 
 class Chef
   class Resource
+    # Use the paludis_package resource to manage packages for the Paludis platform.
+    #
+    # @since 12.1
     class PaludisPackage < Chef::Resource::Package
       resource_name :paludis_package
       provides :paludis_package, os: "linux"

data/lib/chef/resource/perl.rb

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

data/lib/chef/resource/portage_package.rb

@@ -20,6 +20,7 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the portage_package resource to manage packages for the Gentoo platform.
     class PortagePackage < Chef::Resource::Package
       resource_name :portage_package
       def initialize(name, run_context = nil)

data/lib/chef/resource/powershell_package.rb

@@ -20,6 +20,11 @@ require "chef/mixin/uris"
 
 class Chef
   class Resource
+    # Use the powershell_package resource to install and manage packages via the Powershell Package Manager for the
+    # Microsoft Windows platform. The powershell_package resource requires administrative access, and a source must be
+    # configured in the Powershell Package Manager via the Register-PackageSource command
+    #
+    # @since 12.16
     class PowershellPackage < Chef::Resource::Package
       include Chef::Mixin::Uris
 

data/lib/chef/resource/powershell_script.rb

@@ -19,6 +19,14 @@ require "chef/resource/windows_script"
 
 class Chef
   class Resource
+    # Use the powershell_script resource to execute a script using the Windows PowerShell interpreter, much like how the
+    # script and script-based resources—bash, csh, perl, python, and ruby—are used. The powershell_script is specific to
+    # the Microsoft Windows platform and the Windows PowerShell interpreter.
+    #
+    # The powershell_script 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 PowershellScript < Chef::Resource::WindowsScript
       provides :powershell_script, os: "windows"
 

data/lib/chef/resource/python.rb

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

data/lib/chef/resource/reboot.rb

@@ -18,31 +18,25 @@
 
 require "chef/resource"
 
-# In using this resource via notifications, it's important to *only* use
-# immediate notifications. Delayed notifications produce unintuitive and
-# probably undesired results.
 class Chef
   class Resource
+    # Use the reboot resource to reboot a node, a necessary step with some
+    # installations on certain platforms. This resource is supported for use on
+    # the Microsoft Windows, macOS, and Linux platforms.
+    #
+    # In using this resource via notifications, it's important to *only* use
+    # immediate notifications. Delayed notifications produce unintuitive and
+    # probably undesired results.
+    #
+    # @since 12.0
     class Reboot < Chef::Resource
-      allowed_actions :request_reboot, :reboot_now, :cancel
-
-      def initialize(name, run_context = nil)
-        super
-        @provider = Chef::Provider::Reboot
-
-        @reason = "Reboot by Chef"
-        @delay_mins = 0
+      resource_name :reboot
 
-        # no default action.
-      end
-
-      def reason(arg = nil)
-        set_or_return(:reason, arg, :kind_of => String)
-      end
+      allowed_actions :request_reboot, :reboot_now, :cancel
+      default_action :nothing # make sure people are quite clear what they want
 
-      def delay_mins(arg = nil)
-        set_or_return(:delay_mins, arg, :kind_of => Integer)
-      end
+      property :reason, String, default: "Reboot by Chef"
+      property :delay_mins, Integer, default: 0
     end
   end
 end

data/lib/chef/resource/registry_key.rb

@@ -21,6 +21,7 @@ require "chef/digester"
 
 class Chef
   class Resource
+    # Use the registry_key resource to create and delete registry keys in Microsoft Windows.
     class RegistryKey < Chef::Resource
       identity_attr :key
       state_attrs :values

data/lib/chef/resource/remote_directory.rb

@@ -23,6 +23,9 @@ require "chef/mixin/securable"
 
 class Chef
   class Resource
+    # Use the remote_directory resource to incrementally transfer a directory from a cookbook to a node. The director
+    # that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY. The
+    # remote_directory resource will obey file specificity.
     class RemoteDirectory < Chef::Resource::Directory
       include Chef::Mixin::Securable
 

data/lib/chef/resource/remote_file.rb

@@ -25,6 +25,8 @@ require "chef/mixin/uris"
 
 class Chef
   class Resource
+    # Use the remote_file resource to transfer a file from a remote location using file specificity. This resource is
+    # similar to the file resource.
     class RemoteFile < Chef::Resource::File
       include Chef::Mixin::Securable
 

data/lib/chef/resource/resource_notification.rb

@@ -20,6 +20,10 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # @author Tyler Ball
+    # @attr [Resource] resource the Chef resource object to notify to
+    # @attr [Action] action the action to notify
+    # @attr [Resource] notifying_resource the Chef resource performing the notification
     class Notification
 
       attr_accessor :resource, :action, :notifying_resource
@@ -30,6 +34,10 @@ class Chef
         @notifying_resource = notifying_resource
       end
 
+      # Is the current notification a duplicate of another notification
+      #
+      # @param [Notification] another notification object to compare to
+      # @return [Boolean] does the resource match
       def duplicates?(other_notification)
         unless other_notification.respond_to?(:resource) && other_notification.respond_to?(:action)
           msg = "only duck-types of Chef::Resource::Notification can be checked for duplication "\
@@ -41,6 +49,9 @@ class Chef
 
       # If resource and/or notifying_resource is not a resource object, this will look them up in the resource collection
       # and fix the references from strings to actual Resource objects.
+      # @param [ResourceCollection] resource_collection
+      #
+      # @return [void]
       def resolve_resource_reference(resource_collection)
         return resource if resource.kind_of?(Chef::Resource) && notifying_resource.kind_of?(Chef::Resource)
 
@@ -55,6 +66,9 @@ class Chef
 
       # This will look up the resource if it is not a Resource Object.  It will complain if it finds multiple
       # resources, can't find a resource, or gets invalid syntax.
+      # @param [ResourceCollection] resource_collection
+      #
+      # @return [void]
       def fix_resource_reference(resource_collection)
         matching_resource = resource_collection.find(resource)
         if Array(matching_resource).size > 1
@@ -84,6 +98,9 @@ is defined near #{notifying_resource.source_line}
 
       # This will look up the notifying_resource if it is not a Resource Object.  It will complain if it finds multiple
       # resources, can't find a resource, or gets invalid syntax.
+      # @param [ResourceCollection] resource_collection
+      #
+      # @return [void]
       def fix_notifier_reference(resource_collection)
         matching_notifier = resource_collection.find(notifying_resource)
         if Array(matching_notifier).size > 1

data/lib/chef/resource/route.rb

@@ -21,6 +21,7 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the route resource to manage the system routing table in a Linux environment.
     class Route < Chef::Resource
       default_action :add
       allowed_actions :add, :delete

data/lib/chef/resource/rpm_package.rb

@@ -21,6 +21,7 @@ require "chef/provider/package/rpm"
 
 class Chef
   class Resource
+    # Use the rpm_package resource to manage packages for the RPM Package Manager platform.
     class RpmPackage < Chef::Resource::Package
       resource_name :rpm_package
       provides :rpm_package, os: %w{linux aix}

data/lib/chef/resource/ruby.rb

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

data/lib/chef/resource/ruby_block.rb

@@ -22,6 +22,9 @@ require "chef/provider/ruby_block"
 
 class Chef
   class Resource
+    # Use the ruby_block resource to execute Ruby code during a chef-client run. Ruby code in the ruby_block resource is
+    # evaluated with other resources during convergence, whereas Ruby code outside of a ruby_block resource is evaluated
+    # before other resources, as the recipe is compiled.
     class RubyBlock < Chef::Resource
       default_action :run
       allowed_actions :create, :run

data/lib/chef/resource/script.rb

@@ -22,6 +22,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # Use the script resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby.
+    # 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 Script < Chef::Resource::Execute
       identity_attr :name
 

data/lib/chef/resource/service.rb

@@ -22,6 +22,7 @@ require "shellwords"
 
 class Chef
   class Resource
+    # Use the service resource to manage a service.
     class Service < Chef::Resource
       identity_attr :service_name
 

data/lib/chef/resource/smartos_package.rb

@@ -21,6 +21,7 @@ require "chef/provider/package/smartos"
 
 class Chef
   class Resource
+    # Use the smartos_package resource to manage packages for the SmartOS platform.
     class SmartosPackage < Chef::Resource::Package
       resource_name :smartos_package
       provides :package, os: "solaris2", platform_family: "smartos"

data/lib/chef/resource/solaris_package.rb

@@ -22,6 +22,7 @@ require "chef/provider/package/solaris"
 
 class Chef
   class Resource
+    # The solaris_package resource is used to manage packages for the Solaris platform.
     class SolarisPackage < Chef::Resource::Package
       resource_name :solaris_package
       provides :package, os: "solaris2", platform_family: "nexentacore"

data/lib/chef/resource/subversion.rb

@@ -21,6 +21,7 @@ require "chef/resource/scm"
 
 class Chef
   class Resource
+    # Use the subversion resource to manage source control resources that exist in a Subversion repository.
     class Subversion < Chef::Resource::Scm
       allowed_actions :force_export
 

data/lib/chef/resource/systemd_unit.rb

@@ -21,6 +21,9 @@ require "iniparse"
 
 class Chef
   class Resource
+    # Use the systemd_unit resource to create, manage, and run systemd units.
+    #
+    # @since 12.11
     class SystemdUnit < Chef::Resource
       resource_name :systemd_unit
 
@@ -46,6 +49,9 @@ class Chef
                                  default: true, desired_state: false
       property :verify, [TrueClass, FalseClass],
                         default: true, desired_state: false
+      property :unit_name, String, desired_state: false,
+                                   identity: true,
+                                   name_property: true
 
       def to_ini
         case content

data/lib/chef/resource/template.rb

@@ -24,6 +24,15 @@ require "chef/mixin/securable"
 
 class Chef
   class Resource
+    # A cookbook template is an Embedded Ruby (ERB) template that is used to dynamically generate static text files.
+    # Templates may contain Ruby expressions and statements, and are a great way to manage configuration files. Use the
+    # template resource to add cookbook templates to recipes; place the corresponding Embedded Ruby (ERB) template file
+    # in a cookbook’s /templates directory.
+    #
+    # Use the template resource to manage the contents of a file using an Embedded Ruby (ERB) template by transferring
+    # files from a sub-directory of COOKBOOK_NAME/templates/ to a specified path located on a host that is running the
+    # chef-client. This resource includes actions and properties from the file resource. Template files managed by the
+    # template resource follow the same file specificity rules as the remote_file and file resources.
     class Template < Chef::Resource::File
       include Chef::Mixin::Securable
 

data/lib/chef/resource/user.rb

@@ -20,6 +20,7 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the user resource to add users, update existing users, remove users, and to lock/unlock user passwords.
     class User < Chef::Resource
       resource_name :user_resource_abstract_base_class # this prevents magickal class name DSL wiring
       identity_attr :username

data/lib/chef/resource/windows_package.rb

@@ -23,6 +23,8 @@ require "chef/win32/error" if RUBY_PLATFORM =~ /mswin|mingw|windows/
 
 class Chef
   class Resource
+    # Use the windows_package resource to manage Microsoft Installer Package (MSI) packages for the Microsoft Windows
+    # platform.
     class WindowsPackage < Chef::Resource::Package
       include Chef::Mixin::Uris
 

data/lib/chef/resource/windows_path.rb

@@ -20,21 +20,16 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the windows_path resource to manage the path environment variable on Microsoft Windows.
+    #
+    # @since 13.4
     class WindowsPath < Chef::Resource
-
-      provides :windows_path, os: "windows"
+      resource_name :windows_path
+      provides :windows_path
 
       allowed_actions :add, :remove
       default_action :add
 
-      def initialize(name, run_context = nil)
-        super
-        @resource_name = :windows_path
-        @path = name
-        @provider = Chef::Provider::WindowsPath
-        @action = :add
-      end
-
       property :path, String, name_property: true
     end
   end