chef 17.0.242-universal-mingw32 → 17.4.25-universal-mingw32

data/lib/chef/resource/macos_userdefaults.rb

@@ -140,7 +140,7 @@ class Chef
         state_cmd
       end
 
-      action :write, description: "Write the value to the specified domain/key" do
+      action :write, description: "Write the value to the specified domain/key." do
         converge_if_changed do
           cmd = defaults_modify_cmd
           Chef::Log.debug("Updating defaults value by shelling out: #{cmd.join(" ")}")
@@ -149,7 +149,7 @@ class Chef
         end
       end
 
-      action :delete, description: "Delete a key from a domain" do
+      action :delete, description: "Delete a key from a domain." do
         # if it's not there there's nothing to remove
         return unless current_resource
 

data/lib/chef/resource/ohai_hint.rb

@@ -72,9 +72,7 @@ class Chef
         description: "Determines whether or not the resource is executed during the compile time phase.",
         default: true, desired_state: false
 
-      action :create do
-        description "Create an Ohai hint file."
-
+      action :create, description: "Create an Ohai hint file." do
         directory ::Ohai::Config.ohai.hints_path.first do
           action :create
           recursive true
@@ -86,9 +84,7 @@ class Chef
         end
       end
 
-      action :delete do
-        description "Delete an Ohai hint file."
-
+      action :delete, description: "Delete an Ohai hint file." do
         file ohai_hint_file_path(new_resource.hint_name) do
           action :delete
           notifies :reload, ohai[reload ohai post hint removal]

data/lib/chef/resource/openbsd_package.rb

@@ -31,6 +31,23 @@ class Chef
 
       description "Use the **openbsd_package** resource to manage packages for the OpenBSD platform."
       introduced "12.1"
+      examples <<~DOC
+        **Install a package**
+
+        ```ruby
+        openbsd_package 'name of package' do
+          action :install
+        end
+        ```
+
+        **Remove a package**
+
+        ```ruby
+        openbsd_package 'name of package' do
+          action :remove
+        end
+        ```
+      DOC
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",

data/lib/chef/resource/openssl_dhparam.rb

@@ -88,8 +88,7 @@ class Chef
         description: "The permission mode applied to all files created by the resource.",
         default: "0640"
 
-      action :create do
-        description "Create the dhparam file."
+      action :create, description: "Create the `dhparam.pem` file." do
         dhparam_content = nil
         unless dhparam_pem_valid?(new_resource.path)
           dhparam_content = gen_dhparam(new_resource.key_length, new_resource.generator).to_pem

data/lib/chef/resource/openssl_ec_private_key.rb

@@ -88,9 +88,7 @@ class Chef
         description: "Force creation of the key even if the same key already exists on the node.",
         default: false, desired_state: false
 
-      action :create do
-        description "Generate the ec private key"
-
+      action :create, description: "Generate the EC private key file." do
         unless new_resource.force || priv_key_file_valid?(new_resource.path, new_resource.key_pass)
           converge_by("Create an EC private key #{new_resource.path}") do
             log "Generating an #{new_resource.key_curve} "\

data/lib/chef/resource/openssl_ec_public_key.rb

@@ -74,9 +74,7 @@ class Chef
         description: "The permission mode applied to all files created by the resource.",
         default: "0640"
 
-      action :create do
-        description "Generate the ec public key from a private key"
-
+      action :create, description: "Generate the EC public key file from a private key." do
         raise ArgumentError, "You cannot specify both 'private_key_path' and 'private_key_content' properties at the same time." if new_resource.private_key_path && new_resource.private_key_content
         raise ArgumentError, "You must specify the private key with either 'private_key_path' or 'private_key_content' properties." unless new_resource.private_key_path || new_resource.private_key_content
         raise "#{new_resource.private_key_path} not a valid private EC key or password is invalid" unless priv_key_file_valid?((new_resource.private_key_path || new_resource.private_key_content), new_resource.private_key_pass)

data/lib/chef/resource/openssl_rsa_private_key.rb

@@ -87,9 +87,7 @@ class Chef
         description: "Force creation of the key even if the same key already exists on the node.",
         default: false, desired_state: false
 
-      action :create do
-        description "Create the RSA private key."
-
+      action :create, description: "Create the RSA private key file." do
         return if new_resource.force || priv_key_file_valid?(new_resource.path, new_resource.key_pass)
 
         converge_by("create #{new_resource.key_length} bit RSA key #{new_resource.path}") do

data/lib/chef/resource/openssl_rsa_public_key.rb

@@ -75,9 +75,7 @@ class Chef
         description: "The permission mode applied to all files created by the resource.",
         default: "0640"
 
-      action :create do
-        description "Create the RSA public key."
-
+      action :create, description: "Create the RSA public key file." do
         raise ArgumentError, "You cannot specify both 'private_key_path' and 'private_key_content' properties at the same time." if new_resource.private_key_path && new_resource.private_key_content
         raise ArgumentError, "You must specify the private key with either 'private_key_path' or 'private_key_content' properties." unless new_resource.private_key_path || new_resource.private_key_content
         raise "#{new_resource.private_key_path} not a valid private RSA key or password is invalid" unless priv_key_file_valid?((new_resource.private_key_path || new_resource.private_key_content), new_resource.private_key_pass)

data/lib/chef/resource/openssl_x509_certificate.rb

@@ -151,15 +151,12 @@ class Chef
         description: "The number of days before the expiry. The certificate will be automatically renewed when the value is reached.",
         introduced: "15.7"
 
-      action :create do
-        description "Generate a certificate"
-
+      action :create, description: "Generate a certificate file." do
         file new_resource.path do
           action :create_if_missing
           owner new_resource.owner unless new_resource.owner.nil?
           group new_resource.group unless new_resource.group.nil?
           mode new_resource.mode unless new_resource.mode.nil?
-          sensitive true
           content cert.to_pem
         end
 

data/lib/chef/resource/openssl_x509_crl.rb

@@ -90,9 +90,7 @@ class Chef
       property :mode, [Integer, String],
         description: "The permission mode of the CRL file."
 
-      action :create do
-        description "Create the CRL file."
-
+      action :create, description: "Create the certificate revocation list (CRL) file." do
         file new_resource.path do
           owner new_resource.owner unless new_resource.owner.nil?
           group new_resource.group unless new_resource.group.nil?

data/lib/chef/resource/openssl_x509_request.rb

@@ -119,9 +119,7 @@ class Chef
         equal_to: %w{secp384r1 secp521r1 prime256v1}, default: "prime256v1",
         description: "The desired curve of the generated key (if key_type is equal to `ec`). Run `openssl ecparam -list_curves` to see available options."
 
-      action :create do
-        description "Generate a certificate request."
-
+      action :create, description: "Generate a certificate request file." do
         unless ::File.exist? new_resource.path
           converge_by("Create CSR #{@new_resource}") do
             file new_resource.path do

data/lib/chef/resource/osx_profile.rb

@@ -51,7 +51,7 @@ class Chef
         'PayloadOrganization' => 'Chef',
         'PayloadVersion' => 1,
         'PayloadDisplayName' => 'Screensaver Settings',
-        'PayloadContent'=> [
+        'PayloadContent' => [
           {
             'PayloadType' => 'com.apple.ManagedClient.preferences',
             'PayloadVersion' => 1,
@@ -172,7 +172,7 @@ class Chef
         end
       end
 
-      action :install do
+      action :install, description: "Install the specified configuration profile." do
         unless profile_installed?
           converge_by("install profile #{new_profile_identifier}") do
             profile_path = write_profile_to_disk
@@ -182,7 +182,7 @@ class Chef
         end
       end
 
-      action :remove do
+      action :remove, description: "Remove the specified configuration profile." do
         # Clean up profile after removing it
         if profile_installed?
           converge_by("remove profile #{new_profile_identifier}") do

data/lib/chef/resource/plist.rb

@@ -81,7 +81,7 @@ class Chef
         group file_group_cmd.stdout.chomp
       end
 
-      action :set do
+      action :set, description: "Set a value in a plist file." do
         converge_if_changed :path do
           converge_by "create new plist: '#{new_resource.path}'" do
             file new_resource.path do

data/lib/chef/resource/powershell_package_source.rb

@@ -70,8 +70,7 @@ class Chef
         script_publish_location status["script_publish_location"]
       end
 
-      action :register do
-        description "Registers and updates the powershell package source."
+      action :register, description: "Registers and updates the PowerShell package source." do
         # TODO: Ensure package provider is installed?
         if psrepository_cmdlet_appropriate?
           if package_source_exists?
@@ -104,8 +103,7 @@ class Chef
         end
       end
 
-      action :unregister do
-        description "Unregisters the powershell package source."
+      action :unregister, description: "Unregisters the PowerShell package source." do
         if package_source_exists?
           unregister_cmd = "Get-PackageSource -Name '#{new_resource.source_name}' | Unregister-PackageSource"
           converge_by("unregister source: #{new_resource.source_name}") do

data/lib/chef/resource/reboot.rb

@@ -33,6 +33,41 @@ class Chef
                   " immediate notifications. Delayed notifications produce unintuitive and"\
                   " probably undesired results."
       introduced "12.0"
+      examples <<~DOC
+        **Reboot a node immediately**
+
+        ```ruby
+        reboot 'now' do
+          action :nothing
+          reason 'Cannot continue Chef run without a reboot.'
+          delay_mins 2
+        end
+
+        execute 'foo' do
+          command '...'
+          notifies :reboot_now, 'reboot[now]', :immediately
+        end
+        ```
+
+        **Reboot a node at the end of a Chef Infra Client run**
+
+        ```ruby
+        reboot 'app_requires_reboot' do
+          action :request_reboot
+          reason 'Need to reboot when the run completes successfully.'
+          delay_mins 5
+        end
+        ```
+
+        **Cancel a reboot**
+
+        ```ruby
+        reboot 'cancel_reboot_request' do
+          action :cancel
+          reason 'Cancel a previous end-of-run reboot request.'
+        end
+        ```
+      DOC
 
       property :reason, String,
         description: "A string that describes the reboot action.",
@@ -42,18 +77,14 @@ class Chef
         description: "The amount of time (in minutes) to delay a reboot request.",
         default: 0
 
-      action :request_reboot do
-        description "Reboot a node at the end of a chef-client run."
-
+      action :request_reboot, description: "Reboot a node at the end of a #{ChefUtils::Dist::Infra::PRODUCT} run." do
         converge_by("request a system reboot to occur if the run succeeds") do
           logger.warn "Reboot requested:'#{new_resource.name}'"
           request_reboot
         end
       end
 
-      action :reboot_now do
-        description "Reboot a node so that the chef-client may continue the installation process."
-
+      action :reboot_now, description: "Reboot a node so that the #{ChefUtils::Dist::Infra::PRODUCT} may continue the installation process." do
         converge_by("rebooting the system immediately") do
           logger.warn "Rebooting system immediately, requested by '#{new_resource.name}'"
           request_reboot
@@ -61,9 +92,7 @@ class Chef
         end
       end
 
-      action :cancel do
-        description "Cancel a pending reboot request."
-
+      action :cancel, description: "Cancel a pending reboot request." do
         converge_by("cancel any existing end-of-run reboot request") do
           logger.warn "Reboot canceled: '#{new_resource.name}'"
           node.run_context.cancel_reboot

data/lib/chef/resource/remote_directory.rb

@@ -71,7 +71,7 @@ class Chef
         desired_state: false
 
       property :files_group, [String, Integer],
-        description: "Configure group permissions for files. A string or ID that identifies the group owner by group name, including fully qualified group names such as domain\\group or group@domain. If this value is not specified, existing groups remain unchanged and new group assignments use the default POSIX group (if available).",
+        description: "Configure group permissions for files. A string or ID that identifies the group owner by group name, including fully qualified group names such as `domain\\group` or `group@domain`. If this value is not specified, existing groups remain unchanged and new group assignments use the default POSIX group (if available).",
         regex: Chef::Config[:group_valid_regex]
 
       property :files_mode, [String, Integer, nil],
@@ -80,7 +80,7 @@ class Chef
         regex: /^\d{3,4}$/, default: lazy { 0644 unless Chef::Platform.windows? }
 
       property :files_owner, [String, Integer],
-        description: "Configure owner permissions for files. A string or ID that identifies the group owner by user name, including fully qualified user names such as domain\\user or user@domain. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).",
+        description: "Configure owner permissions for files. A string or ID that identifies the group owner by user name, including fully qualified user names such as `domain\\user` or `user@domain`. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary).",
         regex: Chef::Config[:user_valid_regex]
     end
   end

data/lib/chef/resource/remote_file.rb

@@ -85,7 +85,7 @@ class Chef
       end
 
       property :use_etag, [ TrueClass, FalseClass ], default: true,
-        description: "Enable ETag headers. Set to false to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
+        description: "Enable ETag headers. Set to `false` to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
 
       alias :use_etags :use_etag
 
@@ -142,13 +142,13 @@ class Chef
         end
 
         # if domain is provided in both username and domain
-        if specified_user && ((specified_user.include? '\\') || (specified_user.include? "@")) && specified_domain
+        if specified_user && ((specified_user.include? "\\") || (specified_user.include? "@")) && specified_domain
           raise ArgumentError, "The domain is provided twice. Username: `#{specified_user}`, Domain: `#{specified_domain}`. Please specify domain only once."
         end
 
         if ! specified_user.nil? && specified_domain.nil?
           # Splitting username of format: Domain\Username
-          domain_and_user = user.split('\\')
+          domain_and_user = user.split("\\")
 
           if domain_and_user.length == 2
             domain = domain_and_user[0]

data/lib/chef/resource/rhsm_errata.rb

@@ -46,8 +46,6 @@ class Chef
         name_property: true
 
       action :install, description: "Install a package for a specific errata ID." do
-        description "Installs a package for a specific errata ID."
-
         execute "Install errata packages for #{new_resource.errata_id}" do
           command "#{package_manager_command} update --advisory #{new_resource.errata_id} -y"
           default_env true

data/lib/chef/resource/rhsm_errata_level.rb

@@ -42,11 +42,7 @@ class Chef
         name_property: true
 
       action :install, description: "Install all packages of the specified errata level." do
-        description "Install all packages of the specified errata level."
-
-        if rhel6?
-          yum_package "yum-plugin-security"
-        end
+        yum_package "yum-plugin-security" if rhel6?
 
         execute "Install any #{new_resource.errata_level} errata" do
           command "#{package_manager_command} update --sec-severity=#{new_resource.errata_level.capitalize} -y"

data/lib/chef/resource/rhsm_repo.rb

@@ -26,6 +26,21 @@ class Chef
 
       description "Use the **rhsm_repo** resource to enable or disable Red Hat Subscription Manager repositories that are made available via attached subscriptions."
       introduced "14.0"
+      examples <<~DOC
+        **Enable an RHSM repository**
+
+        ```ruby
+        rhsm_repo 'rhel-7-server-extras-rpms'
+        ```
+
+        **Disable an RHSM repository**
+
+        ```ruby
+        rhsm_repo 'rhel-7-server-extras-rpms' do
+          action :disable
+        end
+        ```
+      DOC
 
       property :repo_name, String,
         description: "An optional property for specifying the repository name if it differs from the resource block's name.",

data/lib/chef/resource/rhsm_subscription.rb

@@ -32,11 +32,11 @@ class Chef
         name_property: true
 
       action :attach, description: "Attach the node to a subscription pool." do
-        execute "Attach subscription pool #{new_resource.pool_id}" do
-          command "subscription-manager attach --pool=#{new_resource.pool_id}"
-          default_env true
-          action :run
-          not_if { subscription_attached?(new_resource.pool_id) }
+        unless subscription_attached?(new_resource.pool_id)
+          converge_by("attach subscription pool #{new_resource.pool_id}") do
+            shell_out!("subscription-manager attach --pool=#{new_resource.pool_id}")
+            build_resource(:package, "rhsm_subscription-#{new_resource.pool_id}-flush_cache").run_action(:flush_cache)
+          end
         end
       end
 

data/lib/chef/resource/ruby_block.rb

@@ -29,6 +29,106 @@ 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."
+      examples <<~'DOC'
+        **Reload Chef Infra Client configuration data**
+
+        ```ruby
+        ruby_block 'reload_client_config' do
+          block do
+            Chef::Config.from_file('/etc/chef/client.rb')
+          end
+          action :run
+        end
+        ```
+
+        **Run a block on a particular platform**
+
+        The following example shows how an if statement can be used with the `windows?` method in the Chef Infra Language to run code specific to Microsoft Windows. The code is defined using the ruby_block resource:
+
+        ```ruby
+        if windows?
+          ruby_block 'copy libmysql.dll into ruby path' do
+            block do
+              require 'fileutils'
+              FileUtils.cp "#{node['mysql']['client']['lib_dir']}\\libmysql.dll",
+                node['mysql']['client']['ruby_dir']
+            end
+            not_if { ::File.exist?("#{node['mysql']['client']['ruby_dir']}\\libmysql.dll") }
+          end
+        end
+        ```
+
+        **Stash a file in a data bag**
+
+        The following example shows how to use the ruby_block resource to stash a BitTorrent file in a data bag so that it can be distributed to nodes in the organization.
+
+        ```ruby
+        ruby_block 'share the torrent file' do
+          block do
+            f = File.open(node['bittorrent']['torrent'],'rb')
+            #read the .torrent file and base64 encode it
+            enc = Base64.encode64(f.read)
+            data = {
+              'id'=>bittorrent_item_id(node['bittorrent']['file']),
+              'seed'=>node.ipaddress,
+              'torrent'=>enc
+            }
+            item = Chef::DataBagItem.new
+            item.data_bag('bittorrent')
+            item.raw_data = data
+            item.save
+          end
+          action :nothing
+          subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately
+        end
+        ```
+
+        **Update the /etc/hosts file**
+
+        The following example shows how the ruby_block resource can be used to update the /etc/hosts file:
+
+        ```ruby
+        ruby_block 'edit etc hosts' do
+          block do
+            rc = Chef::Util::FileEdit.new('/etc/hosts')
+            rc.search_file_replace_line(/^127\.0\.0\.1 localhost$/,
+              '127.0.0.1 #{new_fqdn} #{new_hostname} localhost')
+            rc.write_file
+          end
+        end
+        ```
+
+        **Set environment variables**
+
+        The following example shows how to use variables within a Ruby block to set environment variables using rbenv.
+
+        ```ruby
+        node.override[:rbenv][:root] = rbenv_root
+        node.override[:ruby_build][:bin_path] = rbenv_binary_path
+
+        ruby_block 'initialize' do
+          block do
+            ENV['RBENV_ROOT'] = node[:rbenv][:root]
+            ENV['PATH'] = "#{node[:rbenv][:root]}/bin:#{node[:ruby_build][:bin_path]}:#{ENV['PATH']}"
+          end
+        end
+        ```
+
+        **Call methods in a gem**
+
+        The following example shows how to call methods in gems not shipped in Chef Infra Client
+
+        ```ruby
+        chef_gem 'mongodb'
+
+        ruby_block 'config_replicaset' do
+          block do
+            MongoDB.configure_replicaset(node, replicaset_name, rs_nodes)
+          end
+          action :run
+        end
+        ```
+      DOC
 
       default_action :run
       allowed_actions :create, :run