bolt 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb26f585ef72c98683208ddbed3f04cfeb20a035a252604bf73927354ccae4ba
-  data.tar.gz: ad2f911f3e960a4c8ae42586c68466f8526d454d8b227391ac8032614176baa7
+  metadata.gz: 7e32573bc97fea7eca64b7c915cb4b462e1325fb5d4dcbe95c48c72aae8c0e14
+  data.tar.gz: abb279c5a363092ca37ddf4eac9de665de9f79aa74c9e0af9697910b336b7b93
 SHA512:
-  metadata.gz: aa283cf489870b48c9b44098c6f4cd0b805ac963c86369481dae603997a3dd150025273ca9168a6c93538ee60acbcfca16fa524951a6e6dcc59a61212d682da9
-  data.tar.gz: cd7b62972011560ac21404e0589169f0ab690faaa7f17b8138bc09ad30637ac66fb1823f21714ea30c7526c637c7fec89e3d4fe237ad1ca753a6c1c7f46cc56c
+  metadata.gz: 23bf7042750c180eb618eaafd8af34e014deb5c7ab0dadcce316e92c3aa66e62ae85e89e96f471cc54f17c81eba463f73b776e9aa4581219567ed15876722967
+  data.tar.gz: bcd1eb6192f5ac92959088edfbe7b333dcb9ed63f6da7a36a6274d72cbce32e77f4f01a8427edec78be3dd9caeab2472ec3691d846108367df407187606ba2ae

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-service', '2.0.0'
 mod 'puppetlabs-puppet_agent', '4.4.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,20 +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-package', '2.0.0'
 mod 'puppetlabs-powershell_task_helper', '0.1.0'
-mod 'puppetlabs-puppet_conf', '0.8.0'
+mod 'puppetlabs-puppet_conf', '1.0.0'
 mod 'puppetlabs-python_task_helper', '0.5.0'
-mod 'puppetlabs-reboot', '3.2.0'
+mod 'puppetlabs-reboot', '4.0.0'
 mod 'puppetlabs-ruby_task_helper', '0.6.0'
 mod 'puppetlabs-ruby_plugin_helper', '0.2.0'
-mod 'puppetlabs-stdlib', '6.6.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'

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/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] _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] _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,23 @@ 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
 
     executor = Puppet.lookup(:bolt_executor)
     inventory = Puppet.lookup(:bolt_inventory)
@@ -80,7 +102,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/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/lib/bolt/apply_result.rb

@@ -54,7 +54,7 @@ module Bolt
       unless missing_keys.empty?
         if result['_output']
           # rubocop:disable Layout/LineLength
-          msg = "Report result contains an '_output' key. Catalog application may have printed extraneous output to stdout: #{result['_output']}"
+          msg = "Report result contains an '_output' key. Catalog application might have printed extraneous output to stdout: #{result['_output']}"
           # rubocop:enable Layout/LineLength
         else
           msg = "Report did not contain all expected keys missing: #{missing_keys.join(', ')}"

data/lib/bolt/bolt_option_parser.rb

@@ -13,7 +13,7 @@ module Bolt
                 run_context: %w[concurrency inventoryfile save-rerun cleanup],
                 global_config_setters: PROJECT_PATHS + %w[modulepath],
                 transports: %w[transport connect-timeout tty native-ssh ssh-command copy-command],
-                display: %w[format color verbose trace],
+                display: %w[format color verbose trace stream],
                 global: %w[help version log-level clear-cache] }.freeze
 
     ACTION_OPTS = OPTIONS.values.flatten.freeze
@@ -454,7 +454,7 @@ module Bolt
       DESCRIPTION
           Convert a YAML plan to a Puppet language plan and print the converted plan to stdout.
 
-          Converting a YAML plan may result in a plan that is syntactically
+          Converting a YAML plan might result in a plan that is syntactically
           correct but has different behavior. Always verify a converted plan's
           functionality. Note that the converted plan is not written to a file.
 
@@ -707,7 +707,7 @@ module Bolt
              "Or read a target list from an input file '@<file>' or stdin '-'.",
              'Example: --targets localhost,target_group,ssh://nix.com:23,winrm://windows.puppet.com',
              'URI format is [protocol://]host[:port]',
-             "SSH is the default protocol; may be #{TRANSPORTS.keys.join(', ')}",
+             "SSH is the default protocol; can be #{TRANSPORTS.keys.join(', ')}",
              'For Windows targets, specify the winrm:// protocol if it has not be configured',
              'For SSH, port defaults to `22`',
              'For WinRM, port defaults to `5985` or `5986` based on the --[no-]ssl setting') do |targets|
@@ -888,6 +888,9 @@ module Bolt
       define('-v', '--[no-]verbose', 'Display verbose logging') do |value|
         @options[:verbose] = value
       end
+      define('--stream', 'Stream output from scripts and commands to the console') do |_|
+        @options[:stream] = true
+      end
       define('--trace', 'Display error stack traces') do |_|
         @options[:trace] = true
       end

data/lib/bolt/cli.rb

@@ -175,6 +175,7 @@ module Bolt
     # Completes the setup process by configuring Bolt and log messages
     def finalize_setup
       Bolt::Logger.configure(config.log, config.color, config.disable_warnings)
+      Bolt::Logger.stream = config.stream
       Bolt::Logger.analytics = analytics
       Bolt::Logger.flush_queue
 
@@ -212,7 +213,7 @@ module Bolt
       target_opts = options.keys.select { |opt| %i[query rerun targets].include?(opt) }
       target_string = "'--targets', '--rerun', or '--query'"
       if target_opts.length > 1
-        raise Bolt::CLIError, "Only one targeting option #{target_string} may be specified"
+        raise Bolt::CLIError, "Only one targeting option #{target_string} can be specified"
       elsif target_opts.empty? && options[:subcommand] != 'plan'
         raise Bolt::CLIError, "Command requires a targeting option: #{target_string}"
       end
@@ -249,11 +250,14 @@ module Bolt
         end
       end
 
-      if %w[task plan].include?(options[:subcommand]) && options[:action] == 'run'
+      if %w[task plan script].include?(options[:subcommand]) && options[:action] == 'run'
         if options[:object].nil?
           raise Bolt::CLIError, "Must specify a #{options[:subcommand]} to run"
         end
-        # This may mean that we parsed a parameter as the object
+      end
+
+      # This may mean that we parsed a parameter as the object
+      if %w[task plan].include?(options[:subcommand]) && options[:action] == 'run'
         unless options[:object] =~ /\A([a-z][a-z0-9_]*)?(::[a-z][a-z0-9_]*)*\Z/
           raise Bolt::CLIError,
                 "Invalid #{options[:subcommand]} '#{options[:object]}'"
@@ -301,13 +305,13 @@ module Bolt
       if options[:noop] &&
          !(options[:subcommand] == 'task' && options[:action] == 'run') && options[:subcommand] != 'apply'
         raise Bolt::CLIError,
-              "Option '--noop' may only be specified when running a task or applying manifest code"
+              "Option '--noop' can only be specified when running a task or applying manifest code"
       end
 
       if options[:env_vars]
         unless %w[command script].include?(options[:subcommand]) && options[:action] == 'run'
           raise Bolt::CLIError,
-                "Option '--env-var' may only be specified when running a command or script"
+                "Option '--env-var' can only be specified when running a command or script"
         end
       end
     end
@@ -354,7 +358,7 @@ module Bolt
       if inventory_source && conflicting_options.any?
         Bolt::Logger.warn(
           "cli_overrides",
-          "CLI arguments #{conflicting_options.to_a} may be overridden by Inventory: #{inventory_source}"
+          "CLI arguments #{conflicting_options.to_a} might be overridden by Inventory: #{inventory_source}"
         )
       end
     end
@@ -432,7 +436,7 @@ module Bolt
         return 0
       end
 
-      message = 'There may be processes left executing on some nodes.'
+      message = 'There might be processes left executing on some nodes.'
 
       if %w[task plan].include?(options[:subcommand]) && options[:task_options] && !options[:params_parsed] && pal
         options[:task_options] = pal.parse_params(options[:subcommand], options[:object], options[:task_options])
@@ -501,9 +505,8 @@ module Bolt
             when 'command'
               executor.run_command(targets, options[:object], executor_opts)
             when 'script'
-              script = options[:object]
-              validate_file('script', script)
-              executor.run_script(targets, script, options[:leftovers], executor_opts)
+              script_path = find_file(options[:object])
+              executor.run_script(targets, script_path, options[:leftovers], executor_opts)
             when 'task'
               pal.run_task(options[:object],
                            targets,
@@ -610,7 +613,7 @@ module Bolt
         if plan_arguments['nodes'] || plan_arguments['targets']
           key = plan_arguments.include?('nodes') ? 'nodes' : 'targets'
           raise Bolt::CLIError,
-                "A plan's '#{key}' parameter may be specified using the --#{key} option, but in that " \
+                "A plan's '#{key}' parameter can be specified using the --#{key} option, but in that " \
                 "case it must not be specified as a separate #{key}=<value> parameter nor included " \
                 "in the JSON data passed in the --params option"
         end
@@ -840,6 +843,28 @@ module Bolt
       Bolt::Util.validate_file(type, path, allow_dir)
     end
 
+    # Returns the path to a file. If the path is an absolute or relative to
+    # a file, and the file exists, returns the path as-is. Otherwise, checks if
+    # the path is a Puppet file path and looks for the file in a module's files
+    # directory.
+    #
+    def find_file(path)
+      unless File.exist?(path) || Pathname.new(path).absolute?
+        modulepath = Bolt::Config::Modulepath.new(config.modulepath)
+        modules    = Bolt::Module.discover(modulepath.full_modulepath, config.project)
+        mod, file = path.split(File::SEPARATOR, 2)
+
+        if modules[mod]
+          @logger.debug("Did not find file at #{File.expand_path(path)}, checking in module '#{mod}'")
+          path = File.join(modules[mod].path, 'files', file)
+        end
+      end
+
+      Bolt::Util.validate_file('script', path)
+
+      path
+    end
+
     def rerun
       @rerun ||= Bolt::Rerun.new(config.rerunfile, config.save_rerun)
     end
@@ -868,7 +893,7 @@ module Bolt
       # If the bundled content directory is empty, Bolt is likely installed as a gem.
       if ENV['BOLT_GEM'].nil? && incomplete_install?
         msg = <<~MSG.chomp
-          Bolt may be installed as a gem. To use Bolt reliably and with all of its
+          Bolt might be installed as a gem. To use Bolt reliably and with all of its
           dependencies, uninstall the 'bolt' gem and install Bolt as a package:
           https://puppet.com/docs/bolt/latest/bolt_installing.html
 

data/lib/bolt/config.rb

@@ -419,6 +419,10 @@ module Bolt
       @data['spinner']
     end
 
+    def stream
+      @data['stream']
+    end
+
     def inventoryfile
       @data['inventoryfile']
     end

data/lib/bolt/config/options.rb

@@ -4,6 +4,7 @@ require 'bolt/config/transport/ssh'
 require 'bolt/config/transport/winrm'
 require 'bolt/config/transport/orch'
 require 'bolt/config/transport/local'
+require 'bolt/config/transport/lxd'
 require 'bolt/config/transport/docker'
 require 'bolt/config/transport/remote'
 
@@ -17,6 +18,7 @@ module Bolt
         'winrm'  => Bolt::Config::Transport::WinRM,
         'pcp'    => Bolt::Config::Transport::Orch,
         'local'  => Bolt::Config::Transport::Local,
+        'lxd'    => Bolt::Config::Transport::LXD,
         'docker' => Bolt::Config::Transport::Docker,
         'remote' => Bolt::Config::Transport::Remote
       }.freeze
@@ -423,7 +425,14 @@ module Bolt
           _example: false,
           _default: true
         },
-
+        "stream" => {
+          description: "Whether to stream output from scripts and commands to the console. "\
+                       "**This option is experimental**.",
+          type: [TrueClass, FalseClass],
+          _plugin: false,
+          _default: false,
+          _example: true
+        },
         "tasks" => {
           description: "A list of task names and glob patterns to filter the project's tasks by. This option is used "\
                        "to limit the visibility of tasks for users of the project. For example, project authors "\
@@ -440,8 +449,8 @@ module Bolt
         },
         "trusted-external-command" => {
           description: "The path to an executable on the Bolt controller that can produce external trusted facts. "\
-                       "**External trusted facts are experimental in both Puppet and Bolt and this API may change or "\
-                       "be removed.**",
+                       "**External trusted facts are experimental in both Puppet and Bolt and this API might "\
+                       "change or be removed.**",
           type: String,
           _plugin: false,
           _example: "/etc/puppetlabs/facts/trusted_external.sh"
@@ -475,6 +484,13 @@ module Bolt
           _plugin: true,
           _example: { "cleanup" => false, "tmpdir" => "/tmp/bolt" }
         },
+        "lxd" => {
+          description: "A map of configuration options for the LXD transport. The LXD transport is "\
+                       "experimental and might include breaking changes between minor versions.",
+          type: Hash,
+          _plugin: true,
+          _example: { cleanup: false }
+        },
         "pcp" => {
           description: "A map of configuration options for the pcp transport.",
           type: Hash,
@@ -530,6 +546,7 @@ module Bolt
         puppetdb
         save-rerun
         spinner
+        stream
       ].freeze
 
       # Options that are available in a bolt-project.yaml file
@@ -553,6 +570,7 @@ module Bolt
         puppetdb
         save-rerun
         spinner
+        stream
         tasks
         trusted-external-command
       ].freeze