bolt 2.44.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa7f2db70ebfda5de9128554d289d3506ad0c922dac4042e80e29ad691b04447
-  data.tar.gz: b0eedc91174b14a594352d3033a27c13f4f29dbd038679345568e39bea486bc4
+  metadata.gz: 2e66e28078af9324bb7d5668ee5079535d829913a2dcb4bce65daa4d471d4524
+  data.tar.gz: a821d82c490030be200c0d4ab5dc4a56a1abf1aa862d69d1e4c6a4595e47952d
 SHA512:
-  metadata.gz: 1d5620a57dbf4ba82778704296116f53b162a469557162f766c208a5ca5d01e52fbdb219c8e9e965823dca7224dfd1dec507cb432d0d64fa29604fc117a1930f
-  data.tar.gz: 0fdf98e91e30c49960caf5b67bca32d6698c3df18ce1d75db98831cfc0694ac1ba444c08691e809ba3ecca76d702b16e46154ed5fc65a59db432f27355bf57a0
+  metadata.gz: 120dd18c9478c105387f2ad3634276cbaae05fe3638cc01d378aa9cbb1c423bf737991b7278ab4f96eb0a7cca39cd3d259cbba3d1734cea6ac071ba0695da901
+  data.tar.gz: 61171ff383d06883e6f6ffa0cafc423a80d41ea0f2d45c3c0e4b76c7037a4626ad7a4b8b625e3a013e077b9e96cdafaab06cad6d5a490dae392af3fbb410d0fe

data/Puppetfile

@@ -5,14 +5,14 @@ forge "http://forge.puppetlabs.com"
 moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
-mod 'puppetlabs-service', '1.4.0'
-mod 'puppetlabs-puppet_agent', '4.4.0'
+mod 'puppetlabs-service', '2.0.0'
+mod 'puppetlabs-puppet_agent', '4.5.0'
 mod 'puppetlabs-facts', '1.4.0'
 
 # Core types and providers for Puppet 6
-mod 'puppetlabs-augeas_core', '1.1.1'
+mod 'puppetlabs-augeas_core', '1.1.2'
 mod 'puppetlabs-host_core', '1.0.3'
-mod 'puppetlabs-scheduled_task', '2.3.1'
+mod 'puppetlabs-scheduled_task', '3.0.0'
 mod 'puppetlabs-sshkeys_core', '2.2.0'
 mod 'puppetlabs-zfs_core', '1.2.0'
 mod 'puppetlabs-cron_core', '1.0.5'
@@ -22,19 +22,20 @@ mod 'puppetlabs-yumrepo_core', '1.0.7'
 mod 'puppetlabs-zone_core', '1.0.3'
 
 # Useful additional modules
-mod 'puppetlabs-package', '1.4.0'
-mod 'puppetlabs-puppet_conf', '0.8.0'
+mod 'puppetlabs-package', '2.0.0'
+mod 'puppetlabs-powershell_task_helper', '0.1.0'
+mod 'puppetlabs-puppet_conf', '1.1.0'
 mod 'puppetlabs-python_task_helper', '0.5.0'
-mod 'puppetlabs-reboot', '3.2.0'
+mod 'puppetlabs-reboot', '4.0.2'
 mod 'puppetlabs-ruby_task_helper', '0.6.0'
 mod 'puppetlabs-ruby_plugin_helper', '0.2.0'
-mod 'puppetlabs-stdlib', '6.5.0'
+mod 'puppetlabs-stdlib', '7.0.0'
 
 # Plugin modules
 mod 'puppetlabs-aws_inventory', '0.6.0'
 mod 'puppetlabs-azure_inventory', '0.5.0'
 mod 'puppetlabs-gcloud_inventory', '0.2.0'
-mod 'puppetlabs-http_request', '0.2.1'
+mod 'puppetlabs-http_request', '0.2.2'
 mod 'puppetlabs-pkcs7', '0.1.1'
 mod 'puppetlabs-secure_env_vars', '0.2.0'
 mod 'puppetlabs-terraform', '0.6.1'
@@ -45,3 +46,4 @@ mod 'puppetlabs-yaml', '0.2.0'
 mod 'canary', local: true
 mod 'aggregate', local: true
 mod 'puppetdb_fact', local: true
+mod 'puppet_connect', local: true

data/bolt-modules/boltlib/lib/puppet/functions/add_facts.rb

@@ -7,7 +7,7 @@ require 'bolt/error'
 # > **Note:** Not available in apply block
 Puppet::Functions.create_function(:add_facts) do
   # @param target A target.
-  # @param facts A hash of fact names to values that may include structured facts.
+  # @param facts A hash of fact names to values that can include structured facts.
   # @return A `Target` object.
   # @example Adding facts to a target
   #   add_facts($target, { 'os' => { 'family' => 'windows', 'name' => 'windows' } })

data/bolt-modules/boltlib/lib/puppet/functions/apply_prep.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'bolt/logger'
 require 'bolt/task'
 
 # Installs the `puppet-agent` package on targets if needed, then collects facts,
@@ -131,10 +132,20 @@ Puppet::Functions.create_function(:apply_prep) do
         task = applicator.custom_facts_task
         arguments = { 'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins) }
         results = executor.run_task(targets, task, arguments)
+
         # TODO: Standardize RunFailure type with error above
         raise Bolt::RunFailure.new(results, 'run_task', task.name) unless results.ok?
 
         results.each do |result|
+          # Log a warning if the client version is < 6
+          if unsupported_puppet?(result['clientversion'])
+            Bolt::Logger.deprecate(
+              "unsupported_puppet",
+              "Detected unsupported Puppet agent version #{result['clientversion']} on target "\
+              "#{result.target}. Bolt supports Puppet agent 6.0.0 and higher."
+            )
+          end
+
           inventory.add_facts(result.target, result.value)
         end
       end
@@ -143,4 +154,18 @@ Puppet::Functions.create_function(:apply_prep) do
     # Return nothing
     nil
   end
+
+  # Returns true if the client's major version is < 6.
+  #
+  private def unsupported_puppet?(client_version)
+    if client_version.nil?
+      false
+    else
+      begin
+        Integer(client_version.split('.').first) < 6
+      rescue StandardError
+        false
+      end
+    end
+  end
 end

data/bolt-modules/boltlib/lib/puppet/functions/run_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'bolt/error'
+require 'json'
 
 # Runs a command on the given set of targets and returns the result from each command execution.
 # This function does nothing if the list of targets is empty.
@@ -13,7 +14,7 @@ Puppet::Functions.create_function(:run_command) do
   # @param options A hash of additional options.
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @option options [String] _run_as User to run as using privilege escalation.
-  # @option options [Hash] _env_vars Map of environment variables to set
+  # @option options [Hash[String, Any]] _env_vars Map of environment variables to set
   # @return A list of results, one entry per target.
   # @example Run a command on targets
   #   run_command('hostname', $targets, '_catch_errors' => true)
@@ -31,7 +32,7 @@ Puppet::Functions.create_function(:run_command) do
   # @param options A hash of additional options.
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @option options [String] _run_as User to run as using privilege escalation.
-  # @option options [Hash] _env_vars Map of environment variables to set
+  # @option options [Hash[String, Any]] _env_vars Map of environment variables to set
   # @return A list of results, one entry per target.
   # @example Run a command on targets
   #   run_command('hostname', $targets, 'Get hostname')
@@ -56,6 +57,23 @@ Puppet::Functions.create_function(:run_command) do
     options = options.transform_keys { |k| k.sub(/^_/, '').to_sym }
     options[:description] = description if description
 
+    # Ensure env_vars is a hash and that each hash value is transformed to JSON
+    # so we don't accidentally pass Ruby-style data to the target.
+    if options[:env_vars]
+      unless options[:env_vars].is_a?(Hash)
+        raise Bolt::ValidationError, "Option 'env_vars' must be a hash"
+      end
+
+      if (bad_keys = options[:env_vars].keys.reject { |k| k.is_a?(String) }).any?
+        raise Bolt::ValidationError,
+              "Keys for option 'env_vars' must be strings: #{bad_keys.map(&:inspect).join(', ')}"
+      end
+
+      options[:env_vars] = options[:env_vars].transform_values do |val|
+        [Array, Hash].include?(val.class) ? val.to_json : val
+      end
+    end
+
     executor = Puppet.lookup(:bolt_executor)
     inventory = Puppet.lookup(:bolt_inventory)
 

data/bolt-modules/boltlib/lib/puppet/functions/run_plan.rb

@@ -256,7 +256,7 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
     if nodes_param
       if params['nodes']
         raise ArgumentError,
-              "A plan's 'nodes' parameter may be specified as the second positional argument to " \
+              "A plan's 'nodes' parameter can be specified as the second positional argument to " \
               "run_plan(), but in that case 'nodes' must not be specified in the named arguments " \
               "hash."
       end
@@ -265,7 +265,7 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
     elsif targets_param
       if params['targets']
         raise ArgumentError,
-              "A plan's 'targets' parameter may be specified as the second positional argument to " \
+              "A plan's 'targets' parameter can be specified as the second positional argument to " \
               "run_plan(), but in that case 'targets' must not be specified in the named arguments " \
               "hash."
       end

data/bolt-modules/boltlib/lib/puppet/functions/run_script.rb

@@ -6,19 +6,24 @@
 # > **Note:** Not available in apply block
 Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFunction) do
   # Run a script.
-  # @param script Path to a script to run on target. May be an absolute path or a modulename/filename selector for a
+  # @param script Path to a script to run on target. Can be an absolute path or a modulename/filename selector for a
   #               file in $MODULEROOT/files.
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
   # @param options A hash of additional options.
   # @option options [Array[String]] arguments An array of arguments to be passed to the script.
+  #   Cannot be used with `pwsh_params`.
+  # @option options [Hash] pwsh_params Map of named parameters to pass to a PowerShell script.
+  #   Cannot be used with `arguments`.
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @option options [String] _run_as User to run as using privilege escalation.
-  # @option options [Hash] _env_vars Map of environment variables to set
+  # @option options [Hash[String, Any]] _env_vars Map of environment variables to set.
   # @return A list of results, one entry per target.
   # @example Run a local script on Linux targets as 'root'
   #   run_script('/var/tmp/myscript', $targets, '_run_as' => 'root')
   # @example Run a module-provided script with arguments
   #   run_script('iis/setup.ps1', $target, 'arguments' => ['/u', 'Administrator'])
+  # @example Pass named parameters to a PowerShell script
+  #   run_script('iis/setup.ps1', $target, 'pwsh_params' => { 'User' => 'Administrator' })
   dispatch :run_script do
     scope_param
     param 'String[1]', :script
@@ -28,15 +33,18 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
   end
 
   # Run a script, logging the provided description.
-  # @param script Path to a script to run on target. May be an absolute path or a modulename/filename selector for a
+  # @param script Path to a script to run on target. Can be an absolute path or a modulename/filename selector for a
   #               file in $MODULEROOT/files.
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
   # @param description A description to be output when calling this function.
   # @param options A hash of additional options.
   # @option options [Array[String]] arguments An array of arguments to be passed to the script.
+  #   Cannot be used with `pwsh_params`.
+  # @option options [Hash] pwsh_params Map of named parameters to pass to a PowerShell script.
+  #   Cannot be used with `arguments`.
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @option options [String] _run_as User to run as using privilege escalation.
-  # @option options [Hash] _env_vars Map of environment variables to set
+  # @option options [Hash[String, Any]] _env_vars Map of environment variables to set.
   # @return A list of results, one entry per target.
   # @example Run a script
   #   run_script('/var/tmp/myscript', $targets, 'Downloading my application')
@@ -59,9 +67,40 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
         .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'run_script')
     end
 
+    if options.key?('arguments') && options.key?('pwsh_params')
+      raise Bolt::ValidationError, "Cannot specify both 'arguments' and 'pwsh_params'"
+    end
+
+    if options.key?('pwsh_params') && !options['pwsh_params'].is_a?(Hash)
+      raise Bolt::ValidationError, "Option 'pwsh_params' must be a hash"
+    end
+
+    if options.key?('arguments') && !options['arguments'].is_a?(Array)
+      raise Bolt::ValidationError, "Option 'arguments' must be an array"
+    end
+
     arguments = options['arguments'] || []
+    pwsh_params = options['pwsh_params']
     options = options.select { |opt| opt.start_with?('_') }.transform_keys { |k| k.sub(/^_/, '').to_sym }
     options[:description] = description if description
+    options[:pwsh_params] = pwsh_params if pwsh_params
+
+    # Ensure env_vars is a hash and that each hash value is transformed to JSON
+    # so we don't accidentally pass Ruby-style data to the target.
+    if options[:env_vars]
+      unless options[:env_vars].is_a?(Hash)
+        raise Bolt::ValidationError, "Option 'env_vars' must be a hash"
+      end
+
+      if (bad_keys = options[:env_vars].keys.reject { |k| k.is_a?(String) }).any?
+        raise Bolt::ValidationError,
+              "Keys for option 'env_vars' must be strings: #{bad_keys.map(&:inspect).join(', ')}"
+      end
+
+      options[:env_vars] = options[:env_vars].transform_values do |val|
+        [Array, Hash].include?(val.class) ? val.to_json : val
+      end
+    end
 
     executor = Puppet.lookup(:bolt_executor)
     inventory = Puppet.lookup(:bolt_inventory)
@@ -80,7 +119,7 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
         Puppet::Pops::Issues::NOT_A_FILE, file: script
       )
     end
-
+    executor.report_file_source(self.class.name, script)
     # Ensure that given targets are all Target instances)
     targets = inventory.get_targets(targets)
 

data/bolt-modules/boltlib/lib/puppet/functions/upload_file.rb

@@ -76,7 +76,7 @@ Puppet::Functions.create_function(:upload_file, Puppet::Functions::InternalFunct
         Puppet::Pops::Issues::NO_SUCH_FILE_OR_DIRECTORY, file: source
       )
     end
-
+    executor.report_file_source(self.class.name, source)
     # Ensure that that given targets are all Target instances
     targets = inventory.get_targets(targets)
     if targets.empty?

data/bolt-modules/boltlib/lib/puppet/functions/wait_until_available.rb

@@ -2,7 +2,11 @@
 
 require 'bolt/util'
 
-# Wait until all targets accept connections.
+# Wait until all targets accept connections. This function allows a plan execution to wait for a customizable
+# amount of time via the `wait_time` option until a target connection can be reestablished. The plan proceeds
+# to the next step if the connection fails to reconnect in the time specified (default: 120 seconds). A typical
+# use case for this function is if your plan reboots a remote host and the plan needs to wait for the host to reconnect
+# before it continues to the next step.
 #
 # > **Note:** Not available in apply block
 Puppet::Functions.create_function(:wait_until_available) do
@@ -10,8 +14,8 @@ Puppet::Functions.create_function(:wait_until_available) do
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
   # @param options A hash of additional options.
   # @option options [String] description A description for logging. (default: 'wait until available')
-  # @option options [Numeric] wait_time The time to wait. (default: 120)
-  # @option options [Numeric] retry_interval The interval to wait before retrying. (default: 1)
+  # @option options [Numeric] wait_time The time to wait, in seconds. (default: 120)
+  # @option options [Numeric] retry_interval The interval to wait before retrying, in seconds. (default: 1)
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @return A list of results, one entry per target. Successful results have no value.
   # @example Wait for targets

data/bolt-modules/file/lib/puppet/functions/file/read.rb

@@ -17,7 +17,8 @@ Puppet::Functions.create_function(:'file::read', Puppet::Functions::InternalFunc
 
   def read(scope, filename)
     # Send Analytics Report
-    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+    executor = Puppet.lookup(:bolt_executor) {}
+    executor&.report_function_call(self.class.name)
 
     found = Puppet::Parser::Files.find_file(filename, scope.compiler.environment)
     unless found && Puppet::FileSystem.exist?(found)
@@ -25,7 +26,7 @@ Puppet::Functions.create_function(:'file::read', Puppet::Functions::InternalFunc
         Puppet::Pops::Issues::NO_SUCH_FILE_OR_DIRECTORY, file: filename
       )
     end
-
+    executor&.report_file_source(self.class.name, filename)
     File.read(found)
   end
 end

data/bolt-modules/prompt/lib/puppet/functions/prompt.rb

@@ -11,12 +11,24 @@ Puppet::Functions.create_function(:prompt) do
   # @option options [Boolean] sensitive Disable echo back and mark the response as sensitive.
   #   The returned value will be wrapped by the `Sensitive` data type. To access the raw
   #   value, use the `unwrap` function (i.e. `$sensitive_value.unwrap`).
+  # @option options [String] default The default value to return if the user does not provide
+  #   input or if stdin is not a tty.
   # @return The response to the prompt.
   # @example Prompt the user if plan execution should continue
   #   $response = prompt('Continue executing plan? [Y\N]')
   # @example Prompt the user for sensitive information
   #   $password = prompt('Enter your password', 'sensitive' => true)
   #   out::message("Password is: ${password.unwrap}")
+  # @example Prompt the user and provide a default value
+  #   $user = prompt('Enter your login username', 'default' => 'root')
+  # @example Prompt the user for sensitive information, returning a sensitive default if one is not provided
+  #   $token = prompt('Enter token', 'default' => lookup('default_token'), 'sensitive' => true)
+  #   out::message("Token is: ${token.unwrap}")
+  # @example Prompt the user and fail with a custom message if no input was provided
+  #   $response = prompt('Enter your name', 'default' => '')
+  #   if $response.empty {
+  #     fail_plan('Must provide your name')
+  #   }
   dispatch :prompt do
     param 'String', :prompt
     optional_param 'Hash[String[1], Any]', :options
@@ -30,14 +42,20 @@ Puppet::Functions.create_function(:prompt) do
                               action: 'prompt')
     end
 
-    options = options.transform_keys(&:to_sym)
-
+    options  = options.transform_keys(&:to_sym)
     executor = Puppet.lookup(:bolt_executor)
+
     # Send analytics report
     executor.report_function_call(self.class.name)
 
+    # Require default to be a string value
+    if options.key?(:default) && !options[:default].is_a?(String)
+      raise Bolt::ValidationError, "Option 'default' must be a string"
+    end
+
     response = executor.prompt(prompt, options)
 
+    # If sensitive, wrap it
     if options[:sensitive]
       Puppet::Pops::Types::PSensitiveType::Sensitive.new(response)
     else

data/bolt-modules/prompt/lib/puppet/functions/prompt/menu.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Display a menu prompt and wait for a response. Continues to prompt
+# until an option from the menu is selected.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'prompt::menu') do
+  # Select from a list of options.
+  # @param prompt The prompt to display.
+  # @param menu A list of options to choose from.
+  # @param options A hash of additional options.
+  # @option options [String] default The default option to return if the user does not provide
+  #   input or if standard in (stdin) is not a tty. Must be an option present in the menu.
+  # @return The selected option.
+  # @example Prompt the user to select from a list of options
+  #   $selection = prompt::menu('Select a fruit', ['apple', 'banana', 'carrot'])
+  # @example Prompt the user to select from a list of options with a default value
+  #   $selection = prompt::menu('Select environment', ['development', 'production'], 'default' => 'development')
+  dispatch :prompt_menu_array do
+    param 'String', :prompt
+    param 'Array[Variant[Target, Data]]', :menu
+    optional_param 'Hash[String[1], Variant[Target, Data]]', :options
+    return_type 'Variant[Target, Data]'
+  end
+
+  # Select from a list of options with custom inputs.
+  # @param prompt The prompt to display.
+  # @param menu A hash of options to choose from, where keys are the input used to select a value.
+  # @param options A hash of additional options.
+  # @option options [String] default The default option to return if the user does not provide
+  #   input or if standard in (stdin) is not a tty. Must be an option present in the menu.
+  # @return The selected option.
+  # @example Prompt the user to select from a list of options with custom inputs
+  #   $menu = { 'y' => 'yes', 'n' => 'no' }
+  #   $selection = prompt::menu('Install Puppet?', $menu)
+  dispatch :prompt_menu do
+    param 'String', :prompt
+    param 'Hash[String[1], Variant[Target, Data]]', :menu
+    optional_param 'Hash[String[1], Variant[Target, Data]]', :options
+    return_type 'Variant[TargetSpec, Data]'
+  end
+
+  def prompt_menu_array(prompt, menu, options = {})
+    menu_hash = menu.map.with_index { |value, index| [(index + 1).to_s, value] }.to_h
+    prompt_menu(prompt, menu_hash, options)
+  end
+
+  def prompt_menu(prompt, menu, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'prompt::menu')
+    end
+
+    options  = options.transform_keys(&:to_sym)
+    executor = Puppet.lookup(:bolt_executor)
+
+    # Send analytics report
+    executor.report_function_call(self.class.name)
+
+    # Error if there are no options
+    if menu.empty?
+      raise Bolt::ValidationError, "Menu cannot be empty"
+    end
+
+    # Error if the default value is not on the menu
+    if options.key?(:default) && !menu.value?(options[:default])
+      raise Bolt::ValidationError, "Default value '#{options[:default]}' is not one of the provided menu options"
+    end
+
+    # The first prompt should include the menu
+    to_prompt = format_menu(menu) + prompt
+
+    # Request input from the user until they provide a valid option
+    loop do
+      selection = executor.prompt(to_prompt, options)
+
+      return menu[selection] if menu.key?(selection)
+      return selection       if options.key?(:default) && options[:default] == selection
+
+      # Only reprint the prompt, not the menu
+      to_prompt = "Invalid option, try again. #{prompt}"
+    end
+  end
+
+  # Builds the menu string. Aligns all the values by padding input keys.
+  #
+  private def format_menu(menu)
+    # Find the longest input and add 2 for wrapping parenthesis
+    key_length = menu.keys.max_by(&:length).length + 2
+
+    menu_string = +''
+
+    menu.each do |key, value|
+      key = "(#{key})".ljust(key_length)
+      menu_string << "#{key} #{value}\n"
+    end
+
+    menu_string
+  end
+end