bolt 2.18.0 → 2.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87eb513700afc2d9fefa9f2497e8718f0e14e511ea2004c59eecfcb19e41bdbc
-  data.tar.gz: 499d4c8a1a3c0d4b883d83f6478019467a44999beba83712ce49a30ee2ff1fc8
+  metadata.gz: f58ca99a18fca1c109d531c61b55bcee45d73c14e55a074575ffaaf1d9f40aac
+  data.tar.gz: ea55e4c9b9ba4ccd8afed70a6c62c603a119a46f406b573f429bd2cd89983672
 SHA512:
-  metadata.gz: 6046f666fe9bccc4df2a70b191582b14b834063caf31987c1131e7e7c57ac9280e0bf76d719f9b82f27f5de7205b744a2dd3d485f53e9aa867661b824a5b0945
-  data.tar.gz: fc77aa2acd93b4aab739f468a2aa6a6a2da2c9c10bbc4927005f60aeb20148ecb29884d6f2c6cf86bf84d76af276a55f1a8588734157444ab5844c0b9d9878c9
+  metadata.gz: dc8845ebe2a171ce79b704c474594a9679e7078feaca324eb7f26b88e9e903de43361a4dbaa357de3cf47be4ae72b4db4690a76e0910c9595f52aab384768fbc
+  data.tar.gz: 60b30a31debf0d031902d8df21372b2524246ee98749eeccfd588c00b3458bcb9c0ed2a1fbdeab266cce86332537bde1005aead37fece867d440d88989c2486d

data/Puppetfile

@@ -5,7 +5,7 @@ forge "http://forge.puppetlabs.com"
 moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
-mod 'puppetlabs-service', '1.2.0'
+mod 'puppetlabs-service', '1.3.0'
 mod 'puppetlabs-puppet_agent', '3.2.0'
 mod 'puppetlabs-facts', '1.0.0'
 
@@ -28,6 +28,7 @@ mod 'puppetlabs-python_task_helper', '0.4.3'
 mod 'puppetlabs-reboot', '3.0.0'
 mod 'puppetlabs-ruby_task_helper', '0.5.1'
 mod 'puppetlabs-ruby_plugin_helper', '0.1.0'
+mod 'puppetlabs-stdlib', '6.3.0'
 
 # Plugin modules
 mod 'puppetlabs-aws_inventory', '0.5.0'
@@ -42,3 +43,4 @@ mod 'puppetlabs-yaml', '0.2.0'
 mod 'canary', local: true
 mod 'aggregate', local: true
 mod 'puppetdb_fact', local: true
+mod 'secure_env_vars', local: true

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'bolt/error'
+
+# Downloads the given file or directory from the given set of targets and saves it to a directory
+# matching the target's name under the given destination directory. Returns the result from each
+# download. This does nothing if the list of targets is empty.
+#
+# > **Note:** Existing content in the destination directory is deleted before downloading from
+# > the targets.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:download_file, Puppet::Functions::InternalFunction) do
+  # Download a file or directory.
+  # @param source The absolute path to the file or directory on the target(s).
+  # @param destination The relative path to the destination directory on the local system. Expands
+  #                    relative to `<project>/downloads/`.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @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.
+  # @return A list of results, one entry per target, with the path to the downloaded file under the
+  #         `path` key.
+  # @example Download a file from multiple Linux targets to a destination directory
+  #   download_file('/etc/ssh/ssh_config', '~/Downloads', $targets)
+  # @example Download a directory from multiple Linux targets to a project downloads directory
+  #   download_file('/etc/ssh', 'ssh', $targets)
+  # @example Download a file from multiple Linux targets and compare its contents to a local file
+  #   $results = download_file($source, $destination, $targets)
+  #
+  #   $local_content = file::read($source)
+  #
+  #   $mismatched_files = $results.filter |$result| {
+  #     $remote_content = file::read($result['path'])
+  #     $remote_content == $local_content
+  #   }
+  dispatch :download_file do
+    param 'String[1]', :source
+    param 'String[1]', :destination
+    param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  # Download a file or directory, logging the provided description.
+  # @param source The absolute path to the file or directory on the target(s).
+  # @param destination The relative path to the destination directory on the local system. Expands
+  #                    relative to `<project>/downloads/`.
+  # @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 [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @return A list of results, one entry per target, with the path to the downloaded file under the
+  #         `path` key.
+  # @example Download a file from multiple Linux targets to a destination directory
+  #   download_file('/etc/ssh/ssh_config', '~/Downloads', $targets, 'Downloading remote SSH config')
+  dispatch :download_file_with_description do
+    param 'String[1]', :source
+    param 'String[1]', :destination
+    param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  def download_file(source, destination, targets, options = {})
+    download_file_with_description(source, destination, targets, nil, options)
+  end
+
+  def download_file_with_description(source, destination, targets, description = nil, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'download_file')
+    end
+
+    options = options.select { |opt| opt.start_with?('_') }.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    options[:description] = description if description
+
+    executor = Puppet.lookup(:bolt_executor)
+    inventory = Puppet.lookup(:bolt_inventory)
+
+    if (destination = destination.strip).empty?
+      raise Bolt::ValidationError, "Destination cannot be an empty string"
+    end
+
+    if (destination = Pathname.new(destination)).absolute?
+      raise Bolt::ValidationError, "Destination must be a relative path, received absolute path #{destination}"
+    end
+
+    # Prevent path traversal so downloads can't be saved outside of the project downloads directory
+    if (destination.each_filename.to_a & %w[. ..]).any?
+      raise Bolt::ValidationError, "Destination must not include path traversal, received #{destination}"
+    end
+
+    # Paths expand relative to the default downloads directory for the project
+    # e.g. ~/.puppetlabs/bolt/downloads/
+    destination = Puppet.lookup(:bolt_project_data).downloads + destination
+
+    # If the destination directory already exists, delete any existing contents
+    if Dir.exist?(destination)
+      FileUtils.rm_r(Dir.glob(destination + '*'), secure: true)
+    end
+
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    # Ensure that that given targets are all Target instances
+    targets = inventory.get_targets(targets)
+    if targets.empty?
+      call_function('debug', "Simulating file download of '#{source}' - no targets given - no action taken")
+      r = Bolt::ResultSet.new([])
+    else
+      r = executor.download_file(targets, source, destination, options)
+    end
+
+    if !r.ok && !options[:catch_errors]
+      raise Bolt::RunFailure.new(r, 'download_file', source)
+    end
+    r
+  end
+end

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

@@ -11,6 +11,9 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
   # @param args A hash of arguments to the plan. Can also include additional options.
   # @option args [Boolean] _catch_errors Whether to catch raised errors.
   # @option args [String] _run_as User to run as using privilege escalation.
+  #   This option sets the [run-as user](privilege_escalation.md) for all
+  #   targets whenever Bolt connects to a target. This is set for all functions
+  #   in the called plan, including `run_plan()`.
   # @return [PlanResult] The result of running the plan. Undef if plan does not explicitly return results.
   # @example Run a plan
   #   run_plan('canary', 'command' => 'false', 'targets' => $targets, '_catch_errors' => true)
@@ -31,6 +34,9 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
   # @param args A hash of arguments to the plan. Can also include additional options.
   # @option args [Boolean] _catch_errors Whether to catch raised errors.
   # @option args [String] _run_as User to run as using privilege escalation.
+  #   This option sets the [run-as user](privilege_escalation.md) for all
+  #   targets whenever Bolt connects to a target. This is set for all functions
+  #   in the called plan, including `run_plan()`.
   # @return [PlanResult] The result of running the plan. Undef if plan does not explicitly return results.
   # @example Run a plan
   #   run_plan('canary', $targets, 'command' => 'false')

data/bolt-modules/ctrl/lib/puppet/functions/ctrl/do_until.rb

@@ -4,30 +4,36 @@
 Puppet::Functions.create_function(:'ctrl::do_until') do
   # @param options A hash of additional options.
   # @option options [Numeric] limit The number of times to repeat the block.
+  # @option options [Numeric] interval The number of seconds to wait before repeating the block.
   # @example Run a task until it succeeds
   #   ctrl::do_until() || {
-  #     run_task('test', $target, _catch_errors => true).ok()
+  #     run_task('test', $target, '_catch_errors' => true).ok()
   #   }
-  #
   # @example Run a task until it succeeds or fails 10 times
   #   ctrl::do_until('limit' => 10) || {
-  #     run_task('test', $target, _catch_errors => true).ok()
+  #     run_task('test', $target, '_catch_errors' => true).ok()
+  #   }
+  # @example Run a task and wait 10 seconds before running it again
+  #   ctrl::do_until('interval' => 10) || {
+  #     run_task('test', $target, '_catch_errors' => true).ok()
   #   }
-  #
   dispatch :do_until do
     optional_param 'Hash[String[1], Any]', :options
     block_param
   end
 
-  def do_until(options = { 'limit' => 0 })
+  def do_until(options = {})
     # Send Analytics Report
     Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
 
-    limit = options['limit']
+    limit = options['limit'] || 0
+    interval = options['interval']
+
     i = 0
     until (x = yield)
       i += 1
       break if limit != 0 && i >= limit
+      Kernel.sleep(interval) if interval
     end
     x
   end

data/bolt-modules/dir/lib/puppet/functions/dir/children.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+# Returns an array containing all of the filenames except for "." and ".." in the given directory.
+Puppet::Functions.create_function(:'dir::children', Puppet::Functions::InternalFunction) do
+  # @param dirname Absolute path or Puppet module name.
+  # @return Array of files in the given directory.
+  # @example List filenames from an absolute path.
+  #   dir::children('/home/user/subdir/')
+  # @example List filenames from a Puppet file path.
+  #   dir::children('puppet_agent')
+  dispatch :children do
+    scope_param
+    required_param 'String', :dirname
+    return_type 'Array'
+  end
+
+  def children(scope, dirname)
+    # Send Analytics Report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+    modname, subpath = dirname.split(File::SEPARATOR, 2)
+    mod_path = scope.compiler.environment.module(modname)&.path
+
+    full_mod_path = File.join(mod_path, subpath || '') if mod_path
+
+    # Expand relative to the project directory if path is relative
+    project = Puppet.lookup(:bolt_project_data)
+    pathname = Pathname.new(dirname)
+    full_dir = pathname.absolute? ? dirname : File.expand_path(File.join(project.path, dirname))
+
+    # Sort for testability
+    Dir.children(full_mod_path || full_dir).sort
+  end
+end

data/bolt-modules/out/lib/puppet/functions/out/message.rb

@@ -12,7 +12,7 @@ Puppet::Functions.create_function(:'out::message') do
   # @example Print a message
   #   out::message('Something went wrong')
   dispatch :output_message do
-    param 'String', :message
+    param 'Any', :message
     return_type 'Undef'
   end
 

data/lib/bolt/analytics.rb

@@ -72,7 +72,7 @@ module Bolt
 
     def self.load_config(filename, logger)
       if File.exist?(filename)
-        YAML.load_file(filename)
+        Bolt::Util.read_optional_yaml_hash(filename, 'analytics')
       else
         unless ENV['BOLT_DISABLE_ANALYTICS']
           logger.warn <<~ANALYTICS

data/lib/bolt/bolt_option_parser.rb

@@ -25,7 +25,7 @@ module Bolt
       when 'command'
         case action
         when 'run'
-          { flags: ACTION_OPTS,
+          { flags: ACTION_OPTS + %w[env-var],
             banner: COMMAND_RUN_HELP }
         else
           { flags: OPTIONS[:global],
@@ -36,6 +36,9 @@ module Bolt
         when 'upload'
           { flags: ACTION_OPTS + %w[tmpdir],
             banner: FILE_UPLOAD_HELP }
+        when 'download'
+          { flags: ACTION_OPTS,
+            banner: FILE_DOWNLOAD_HELP }
         else
           { flags: OPTIONS[:global],
             banner: FILE_HELP }
@@ -63,6 +66,9 @@ module Bolt
         when 'convert'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
             banner: PLAN_CONVERT_HELP }
+        when 'new'
+          { flags: OPTIONS[:global] + %w[configfile project],
+            banner: PLAN_NEW_HELP }
         when 'run'
           { flags: ACTION_OPTS + %w[params compile-concurrency tmpdir hiera-config],
             banner: PLAN_RUN_HELP }
@@ -103,7 +109,7 @@ module Bolt
       when 'script'
         case action
         when 'run'
-          { flags: ACTION_OPTS + %w[tmpdir],
+          { flags: ACTION_OPTS + %w[tmpdir env-var],
             banner: SCRIPT_RUN_HELP }
         else
           { flags: OPTIONS[:global],
@@ -156,10 +162,10 @@ module Bolt
       SUBCOMMANDS
           apply             Apply Puppet manifest code
           command           Run a command remotely
-          file              Upload a local file or directory
+          file              Copy files between the controller and targets
           group             Show the list of groups in the inventory
           inventory         Show the list of targets an action would run on
-          plan              Convert, show, and run Bolt plans
+          plan              Convert, create, show, and run Bolt plans
           project           Create and migrate Bolt projects
           puppetfile        Install and list modules and generate type references
           script            Upload a local script and run it remotely
@@ -218,10 +224,30 @@ module Bolt
           bolt file <action> [options]
 
       DESCRIPTION
-          Upload a local file or directory
+          Copy files and directories between the controller and targets
 
       ACTIONS
-          upload        Upload a local file or directory
+          download      Download a file or directory to the controller
+          upload        Upload a local file or directory from the controller
+    HELP
+
+    FILE_DOWNLOAD_HELP = <<~HELP
+      NAME
+          download
+
+      USAGE
+          bolt file download <src> <dest> [options]
+
+      DESCRIPTION
+          Download a file or directory from one or more targets.
+
+          Downloaded files and directories are saved to the a subdirectory
+          matching the target's name under the destination directory. The
+          destination directory is expanded relative to the downloads
+          subdirectory of the project directory.
+
+      EXAMPLES
+          bolt file download /etc/ssh_config ssh_config -t all
     HELP
 
     FILE_UPLOAD_HELP = <<~HELP
@@ -296,10 +322,11 @@ module Bolt
           bolt plan <action> [parameters] [options]
 
       DESCRIPTION
-          Convert, show, and run Bolt plans.
+          Convert, create, show, and run Bolt plans.
 
       ACTIONS
           convert       Convert a YAML plan to a Bolt plan
+          new           Create a new plan in the current project
           run           Run a plan on the specified targets
           show          Show available plans and plan documentation
     HELP
@@ -322,6 +349,20 @@ module Bolt
           bolt plan convert path/to/plan/myplan.yaml
     HELP
 
+    PLAN_NEW_HELP = <<~HELP
+      NAME
+          new
+      
+      USAGE
+          bolt plan new <plan> [options]
+      
+      DESCRIPTION
+          Create a new plan in the current project.
+
+      EXAMPLES
+          bolt plan new myproject::myplan
+    HELP
+
     PLAN_RUN_HELP = <<~HELP
       NAME
           run
@@ -379,19 +420,18 @@ module Bolt
           init
 
       USAGE
-          bolt project init [directory] [options]
+          bolt project init [name] [options]
 
       DESCRIPTION
-          Create a new Bolt project.
+          Create a new Bolt project in the current working directory.
 
-          Specify a directory to create a Bolt project in. Defaults to the
-          curent working directory.
+          Specify a name for the Bolt project. Defaults to the basename of the current working directory.
 
       EXAMPLES
-          Create a new Bolt project in the current working directory.
+          Create a new Bolt project using the directory as the project name.
             bolt project init
-          Create a new Bolt project at a specified path.
-            bolt project init ~/path/to/project
+          Create a new Bolt project with a specified name.
+            bolt project init myproject
           Create a new Bolt project with existing modules.
             bolt project init --modules puppetlabs-apt,puppetlabs-ntp
     HELP
@@ -594,13 +634,13 @@ module Bolt
             bolt task show canary
     HELP
 
-    attr_reader :warnings
+    attr_reader :deprecations
 
     def initialize(options)
       super()
 
       @options = options
-      @warnings = []
+      @deprecations = []
 
       separator "\nINVENTORY OPTIONS"
       define('-t', '--targets TARGETS',
@@ -653,9 +693,9 @@ module Bolt
         @options[:password] = password
       end
       define('--password-prompt', 'Prompt for user to input password') do |_password|
-        STDERR.print "Please enter your password: "
-        @options[:password] = STDIN.noecho(&:gets).chomp
-        STDERR.puts
+        $stderr.print "Please enter your password: "
+        @options[:password] = $stdin.noecho(&:gets).chomp
+        $stderr.puts
       end
       define('--private-key KEY', 'Path to private ssh key to authenticate with') do |key|
         @options[:'private-key'] = File.expand_path(key)
@@ -679,9 +719,9 @@ module Bolt
         @options[:'sudo-password'] = password
       end
       define('--sudo-password-prompt', 'Prompt for user to input escalation password') do |_password|
-        STDERR.print "Please enter your privilege escalation password: "
-        @options[:'sudo-password'] = STDIN.noecho(&:gets).chomp
-        STDERR.puts
+        $stderr.print "Please enter your privilege escalation password: "
+        @options[:'sudo-password'] = $stdin.noecho(&:gets).chomp
+        $stderr.puts
       end
       define('--sudo-executable EXEC', "Specify an executable for running as another user.",
              "This option is experimental.") do |exec|
@@ -738,6 +778,15 @@ module Bolt
         @options[:'save-rerun'] = save
       end
 
+      separator "\nREMOTE ENVIRONMENT OPTIONS"
+      define('--env-var ENVIRONMENT_VARIABLES', 'Environment variables to set on the target') do |envvar|
+        unless envvar.include?('=')
+          raise Bolt::CLIError, "Environment variables must be specified using 'myenvvar=key' format"
+        end
+        @options[:env_vars] ||= {}
+        @options[:env_vars].store(*envvar.split('=', 2))
+      end
+
       separator "\nTRANSPORT OPTIONS"
       define('--transport TRANSPORT', TRANSPORTS.keys.map(&:to_s),
              "Specify a default transport: #{TRANSPORTS.keys.join(', ')}") do |t|
@@ -809,7 +858,8 @@ module Bolt
         @options[:debug] = true
         # We don't actually set '--log-level debug' here, but once the options are evaluated by
         # the config class the end result is the same.
-        @warnings << { msg: "Command line option '--debug' is deprecated, set '--log-level debug' instead." }
+        msg = "Command line option '--debug' is deprecated, set '--log-level debug' instead."
+        @deprecations << { type: 'Using --debug instead of --log-level debug', msg: msg }
       end
       define('--log-level LEVEL',
              "Set the log level for the console. Available options are",
@@ -854,7 +904,7 @@ module Bolt
         file = value.sub(/^@/, '')
         read_arg_file(file)
       elsif value == '-'
-        STDIN.read
+        $stdin.read
       else
         value
       end