chef 16.6.14-universal-mingw32 → 16.9.17-universal-mingw32

data/lib/chef/resource/python.rb

@@ -31,9 +31,9 @@ class Chef
 
       description "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"\
+                  " 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."
+                  " which they are run. Use `not_if` and `only_if` to guard this resource for idempotence."
     end
   end
 end

data/lib/chef/resource/registry_key.rb

@@ -27,7 +27,96 @@ class Chef
       provides(:registry_key) { true }
 
       description "Use the **registry_key** resource to create and delete registry keys in Microsoft Windows."
-      introduced "11.0"
+      examples <<~'DOC'
+      **Create a registry key**
+
+      ```ruby
+      registry_key 'HKEY_LOCAL_MACHINE\\path-to-key\\Policies\\System' do
+        values [{
+          name: 'EnableLUA',
+          type: :dword,
+          data: 0
+        }]
+        action :create
+      end
+      ```
+
+      **Create a registry key with binary data: "\x01\x02\x03"**:
+
+      ```ruby
+      registry_key 'HKEY_CURRENT_USER\ChefTest' do
+        values [{
+          :name => "test",
+          :type => :binary,
+          :data => [0, 1, 2].map(&:chr).join
+        }]
+        action :create
+      end
+      ```
+
+      **Create 32-bit key in redirected wow6432 tree**
+
+      In 64-bit versions of Microsoft Windows, HKEY_LOCAL_MACHINE\SOFTWARE\Example is a re-directed key. In the following examples, because HKEY_LOCAL_MACHINE\SOFTWARE\Example is a 32-bit key, the output will be “Found 32-bit key” if they are run on a version of Microsoft Windows that is 64-bit:
+
+      ```ruby
+      registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Example' do
+        architecture :i386
+        recursive true
+        action :create
+      end
+      ```
+
+      **Set proxy settings to be the same as those used by Chef Infra Client**
+
+      ```ruby
+      proxy = URI.parse(Chef::Config[:http_proxy])
+      registry_key 'HKCU\Software\Microsoft\path\to\key\Internet Settings' do
+        values [{name: 'ProxyEnable', type: :reg_dword, data: 1},
+                {name: 'ProxyServer', data: "#{proxy.host}:#{proxy.port}"},
+                {name: 'ProxyOverride', type: :reg_string, data: <local>},
+               ]
+        action :create
+      end
+      ```
+
+      **Set the name of a registry key to "(Default)"**
+
+      ```ruby
+      registry_key 'Set (Default) value' do
+        key 'HKLM\Software\Test\Key\Path'
+        values [
+          {name: '', type: :string, data: 'test'},
+        ]
+        action :create
+      end
+      ```
+
+      **Delete a registry key value**
+
+      ```ruby
+      registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\path\to\key\AU' do
+        values [{
+          name: 'NoAutoRebootWithLoggedOnUsers',
+          type: :dword,
+          data: ''
+          }]
+        action :delete
+      end
+      ```
+
+      Note: If data: is not specified, you get an error: Missing data key in RegistryKey values hash
+
+      **Delete a registry key and its subkeys, recursively**
+
+      ```ruby
+      registry_key 'HKCU\SOFTWARE\Policies\path\to\key\Themes' do
+        recursive true
+        action :delete_key
+      end
+      ```
+
+      Note: Be careful when using the :delete_key action with the recursive attribute. This will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by Chef Infra Client.
+      DOC
 
       state_attrs :values
 
@@ -72,6 +161,8 @@ class Chef
 
       property :key, String, name_property: true
 
+      VALID_VALUE_HASH_KEYS = %i{name type data}.freeze
+
       def values(arg = nil)
         if not arg.nil?
           if arg.is_a?(Hash)
@@ -89,7 +180,7 @@ class Chef
             raise ArgumentError, "Missing name key in RegistryKey values hash" unless v.key?(:name)
 
             v.each_key do |key|
-              raise ArgumentError, "Bad key #{key} in RegistryKey values hash" unless %i{name type data}.include?(key)
+              raise ArgumentError, "Bad key #{key} in RegistryKey values hash" unless VALID_VALUE_HASH_KEYS.include?(key)
             end
             raise ArgumentError, "Type of name => #{v[:name]} should be string" unless v[:name].is_a?(String)
 

data/lib/chef/resource/remote_directory.rb

@@ -29,7 +29,7 @@ class Chef
 
       provides :remote_directory
 
-      description "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."
+      description "Use the **remote_directory** resource to incrementally transfer a directory from a cookbook to a node. The directory that is copied from the cookbook should be located under `COOKBOOK_NAME/files/default/REMOTE_DIRECTORY`. The `remote_directory` resource will obey file specificity."
 
       default_action :create
       allowed_actions :create, :create_if_missing, :delete

data/lib/chef/resource/route.rb

@@ -43,7 +43,7 @@ class Chef
         description: "The route metric value."
 
       property :netmask, [String, nil],
-        description: "The decimal representation of the network mask. For example: 255.255.255.0."
+        description: "The decimal representation of the network mask. For example: `255.255.255.0`."
 
       property :gateway, [String, nil],
         description: "The gateway for the route."

data/lib/chef/resource/ruby.rb

@@ -25,11 +25,7 @@ class Chef
 
       provides :ruby
 
-      description "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."
+      description "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."
 
       def initialize(name, run_context = nil)
         super

data/lib/chef/resource/ruby_block.rb

@@ -28,7 +28,7 @@ class Chef
 
       provides :ruby_block, target_mode: true
 
-      description "Use the **ruby_block** resource to execute Ruby code during a #{ChefUtils::Dist::Infra::PRODUCT} 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."
+      description "Use the **ruby_block** resource to execute Ruby code during a #{ChefUtils::Dist::Infra::PRODUCT} 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."
 
       default_action :run
       allowed_actions :create, :run

data/lib/chef/resource/scm/_scm.rb

@@ -33,7 +33,8 @@ property :revision, String,
   default: "HEAD"
 
 property :user, [String, Integer],
-  description: "The system user that will own the checked-out code."
+  description: "The system user that will own the checked-out code.",
+  default_description: "`HOME` environment variable of the user running #{ChefUtils::Dist::Infra::CLIENT}"
 
 property :group, [String, Integer],
   description: "The system group that will own the checked-out code."

data/lib/chef/resource/scm/git.rb

@@ -28,6 +28,87 @@ class Chef
       provides :git
 
       description "Use the **git** resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher) is required to use all of the functionality in the git resource."
+      examples <<~DOC
+      **Use the git mirror**
+
+      ```ruby
+      git '/opt/my_sources/couch' do
+        repository 'git://git.apache.org/couchdb.git'
+        revision 'master'
+        action :sync
+      end
+      ```
+
+      **Use different branches**
+
+      To use different branches, depending on the environment of the node:
+
+      ```ruby
+      branch_name = if node.chef_environment == 'QA'
+                      'staging'
+                    else
+                      'master'
+                    end
+
+      git '/home/user/deployment' do
+         repository 'git@github.com:git_site/deployment.git'
+         revision branch_name
+         action :sync
+         user 'user'
+         group 'test'
+      end
+      ```
+
+      Where the `branch_name` variable is set to staging or master, depending on the environment of the node. Once this is determined, the `branch_name` variable is used to set the revision for the repository. If the git status command is used after running the example above, it will return the branch name as `deploy`, as this is the default value. Run Chef Infra Client in debug mode to verify that the correct branches are being checked out:
+
+      ```
+      sudo chef-client -l debug
+      ```
+
+      **Install an application from git using bash**
+
+      The following example shows how Bash can be used to install a plug-in for rbenv named ruby-build, which is located in git version source control. First, the application is synchronized, and then Bash changes its working directory to the location in which ruby-build is located, and then runs a command.
+
+      ```ruby
+      git "#{Chef::Config[:file_cache_path]}/ruby-build" do
+        repository 'git://github.com/rbenv/ruby-build.git'
+        revision 'master'
+        action :sync
+      end
+
+      bash 'install_ruby_build' do
+        cwd "#{Chef::Config[:file_cache_path]}/ruby-build"
+        user 'rbenv'
+        group 'rbenv'
+        code <<-EOH
+          ./install.sh
+          EOH
+        environment 'PREFIX' => '/usr/local'
+      end
+      ```
+
+      **Notify a resource post-checkout**
+
+      ```ruby
+      git "#{Chef::Config[:file_cache_path]}/my_app" do
+        repository node['my_app']['git_repository']
+        revision node['my_app']['git_revision']
+        action :sync
+        notifies :run, 'bash[compile_my_app]', :immediately
+      end
+      ```
+
+      **Pass in environment variables**
+
+      ```ruby
+      git '/opt/my_sources/couch' do
+        repository 'git://git.apache.org/couchdb.git'
+        revision 'master'
+        environment 'VAR' => 'whatever'
+        action :sync
+      end
+      ```
+      DOC
 
       property :additional_remotes, Hash,
         description: "A Hash of additional remotes that are added to the git repository configuration.",
@@ -41,7 +122,7 @@ class Chef
         default: false
 
       property :enable_checkout, [TrueClass, FalseClass],
-        description: "Check out a repo from master. Set to false when using the checkout_branch attribute to prevent the git resource from attempting to check out master from master.",
+        description: "Check out a repo from master. Set to `false` when using the `checkout_branch` attribute to prevent the git resource from attempting to check out `master` from `master`.",
         default: true
 
       property :remote, String,

data/lib/chef/resource/scm/subversion.rb

@@ -29,6 +29,18 @@ class Chef
       provides :subversion
 
       description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository."
+      examples <<~DOC
+      **Get the latest version of an application**
+
+      ```ruby
+      subversion 'CouchDB Edge' do
+        repository 'http://svn.apache.org/repos/asf/couchdb/trunk'
+        revision 'HEAD'
+        destination '/opt/my_sources/couch'
+        action :sync
+      end
+      ```
+      DOC
 
       allowed_actions :force_export
 

data/lib/chef/resource/script.rb

@@ -29,9 +29,9 @@ class Chef
       identity_attr :name
 
       description "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"\
+                  " 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."
+                  " 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/solaris_package.rb

@@ -25,8 +25,6 @@ class Chef
       unified_mode true
 
       provides :solaris_package
-      provides :package, os: "solaris2", platform_family: "nexentacore"
-      provides :package, os: "solaris2", platform_family: "solaris2", platform_version: "<= 5.10"
 
       description "Use the **solaris_package** resource to manage packages on the Solaris platform."
 

data/lib/chef/resource/sudo.rb

@@ -30,7 +30,7 @@ class Chef
 
       description "Use the **sudo** resource to add or remove individual sudo entries using sudoers.d files."\
                   " Sudo version 1.7.2 or newer is required to use the sudo resource, as it relies on the"\
-                  " '#includedir' directive introduced in version 1.7.2. This resource does not enforce"\
+                  " `#includedir` directive introduced in version 1.7.2. This resource does not enforce"\
                   " installation of the required sudo version. Chef-supported releases of Ubuntu, SuSE, Debian,"\
                   " and RHEL (6+) all support this feature."
       introduced "14.0"

data/lib/chef/resource/support/client.erb

@@ -10,7 +10,6 @@
       @https_proxy
       @ftp_proxy
       @log_level
-      @log_location
       @minimal_ohai
       @named_run_list
       @no_proxy
@@ -21,14 +20,14 @@
       @policy_name
       @ssl_verify_mode).each do |prop| -%>
 <% next if instance_variable_get(prop).nil? || instance_variable_get(prop).empty? -%>
-<%=prop.delete_prefix("@") %> = <%= instance_variable_get(prop).inspect %>
+<%=prop.delete_prefix("@") %> <%= instance_variable_get(prop).inspect %>
 <% end -%>
 <%# log_location is special due to STDOUT/STDERR from String -> IO Object -%>
 <% unless @log_location.nil? %>
-  <% if @log_location.is_a? String && %w(STDOUT STDERR).include?(@log_location) -%>
-log_location = <%= @log_location %>
+  <% if @log_location.is_a?(String) && %w(STDOUT STDERR).include?(@log_location) -%>
+log_location <%= @log_location %>
   <% else -%>
-log_location = <%= @log_location.inspect %>
+log_location <%= @log_location.inspect %>
   <% end -%>
 <% end -%>
 <%# The code below is not DRY on purpose to improve readability -%>

data/lib/chef/resource/systemd_unit.rb

@@ -27,8 +27,49 @@ class Chef
 
       provides(:systemd_unit) { true }
 
-      description "Use the **systemd_unit** resource to create, manage, and run systemd units."
+      description "Use the **systemd_unit** resource to create, manage, and run [systemd units](https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts)."
       introduced "12.11"
+      examples <<~DOC
+      **Create systemd service unit file from a Hash**
+
+      ```ruby
+      systemd_unit 'etcd.service' do
+        content({Unit: {
+                  Description: 'Etcd',
+                  Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'],
+                  After: 'network.target',
+                },
+                Service: {
+                  Type: 'notify',
+                  ExecStart: '/usr/local/etcd',
+                  Restart: 'always',
+                },
+                Install: {
+                  WantedBy: 'multi-user.target',
+                }})
+        action [:create, :enable]
+      end
+      ```
+
+      **Create systemd service unit file from a String**
+
+      ```ruby
+      systemd_unit 'sysstat-collect.timer' do
+        content <<~EOU
+        [Unit]
+        Description=Run system activity accounting tool every 10 minutes
+
+        [Timer]
+        OnCalendar=*:00/10
+
+        [Install]
+        WantedBy=sysstat.service
+        EOU
+
+        action [:create, :enable]
+      end
+      ```
+      DOC
 
       default_action :nothing
       allowed_actions :create, :delete,

data/lib/chef/resource/template.rb

@@ -169,8 +169,8 @@ class Chef
         elsif module_name.nil?
           raise Exceptions::ValidationFailed,
             "#helpers requires either a module name or inline module code as a block.\n" +
-            "e.g.: helpers do; helper_code; end;\n" +
-            "OR: helpers(MyHelpersModule)"
+              "e.g.: helpers do; helper_code; end;\n" +
+              "OR: helpers(MyHelpersModule)"
         else
           raise Exceptions::ValidationFailed,
             "Argument to #helpers must be a module. You gave #{module_name.inspect} (#{module_name.class})"

data/lib/chef/resource/user/windows_user.rb

@@ -29,6 +29,11 @@ class Chef
         property :full_name, String,
           description: "The full name of the user.",
           introduced: "14.6"
+
+        # Override the property from the parent class to coerce to integer.
+        property :uid, [ String, Integer, NilClass ], # nil for backwards compat
+          description: "The numeric user identifier.",
+          coerce: proc { |n| n && Integer(n) rescue n }
       end
     end
   end

data/lib/chef/resource/windows_ad_join.rb

@@ -109,12 +109,12 @@ class Chef
           cmd << " -Force"
 
           converge_by("join Active Directory domain #{new_resource.domain_name}") do
-            ps_run = powershell_out(cmd)
+            ps_run = powershell_exec(cmd)
             if ps_run.error?
               if sensitive?
                 raise "Failed to join the domain #{new_resource.domain_name}: *suppressed sensitive resource output*"
               else
-                raise "Failed to join the domain #{new_resource.domain_name}: #{ps_run.stderr}"
+                raise "Failed to join the domain #{new_resource.domain_name}: #{ps_run.errors}"
               end
             end
 
@@ -143,12 +143,12 @@ class Chef
           cmd << " -Force"
 
           converge_by("leave Active Directory domain #{node_domain}") do
-            ps_run = powershell_out(cmd)
+            ps_run = powershell_exec(cmd)
             if ps_run.error?
               if sensitive?
                 raise "Failed to leave the domain #{node_domain}: *suppressed sensitive resource output*"
               else
-                raise "Failed to leave the domain #{node_domain}: #{ps_run.stderr}"
+                raise "Failed to leave the domain #{node_domain}: #{ps_run.errors}"
               end
             end
 
@@ -170,10 +170,10 @@ class Chef
         #   workgroup the node is a member of.
         #
         def node_domain
-          node_domain = powershell_out!("(Get-WmiObject Win32_ComputerSystem).Domain")
-          raise "Failed to check if the system is joined to the domain #{new_resource.domain_name}: #{node_domain.stderr}}" if node_domain.error?
+          node_domain = powershell_exec!("(Get-WmiObject Win32_ComputerSystem).Domain")
+          raise "Failed to check if the system is joined to the domain #{new_resource.domain_name}: #{node_domain.errors}}" if node_domain.error?
 
-          node_domain.stdout.downcase.strip
+          node_domain.result.downcase.strip
         end
 
         #
@@ -182,10 +182,10 @@ class Chef
         #   workgroup.
         #
         def node_workgroup
-          node_workgroup = powershell_out!("(Get-WmiObject Win32_ComputerSystem).Workgroup")
+          node_workgroup = powershell_exec!("(Get-WmiObject Win32_ComputerSystem).Workgroup")
           raise "Failed to check if the system is currently a member of a workgroup" if node_workgroup.error?
 
-          node_workgroup.stdout.downcase.strip
+          node_workgroup.result
         end
 
         #