bolt 0.18.1 → 0.18.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0658ba25967cd7fac93e3b0c410793f2d389849f
-  data.tar.gz: f7a6cafb673449de219fb9bade1e672d4ff858eb
+  metadata.gz: 5705a6c7d44fd856ef5bf240252574ddb823a336
+  data.tar.gz: 70027049c0bb060a5b04bd7a9ca5b00772466fc4
 SHA512:
-  metadata.gz: 3908b25652b38dd0a7e48656b3442fe6b5e85fd23942dbb2be207f4f4f39397b18d7b87706791075773b53c0d297d0b9ba8743a0070c5bcde8d8d7be11a71ce8
-  data.tar.gz: e837918752a7e2cc2ac2bff3aa72f480c4fcf7f498fca15cf355a9cb2b7bc24faa2e91b1684e7650ead33a06315961ceb6792148b70cff974bc0e960972454ca
+  metadata.gz: 032844c9618c04162ef3bfe3e4ae6eade64f952478906d6b02539d57fd6e4325d38f35ba818e6ff1fb42fa3fd2e7f01a25527666b68560038a0c479a5ec39dfd
+  data.tar.gz: b9df84d3b06f1d24d1c554cd5631f381356b2e0cadcbe2c2685b3b6fe610ca237611877148d5ff7f90064fc08d9925d53bfef6a0c85f0f3f5c516fc6216eb4ca

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

@@ -19,8 +19,24 @@ Puppet::Functions.create_function(:file_upload, Puppet::Functions::InternalFunct
     return_type 'ResultSet'
   end
 
+  dispatch :file_upload_with_description do
+    scope_param
+    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 file_upload(scope, source, destination, targets, options = nil)
+    file_upload_with_description(scope, source, destination, targets, nil, options)
+  end
+
+  def file_upload_with_description(scope, source, destination, targets, description = nil, options = nil)
     options ||= {}
+    options = options.merge('_description' => description) if description
+
     unless Puppet[:tasks]
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
         Puppet::Pops::Issues::TASK_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, operation: 'file_upload'
@@ -48,7 +64,7 @@ Puppet::Functions.create_function(:file_upload, Puppet::Functions::InternalFunct
       call_function('debug', "Simulating file upload of '#{found}' - no targets given - no action taken")
       r = Bolt::ResultSet.new([])
     else
-      r = executor.file_upload(targets, found, destination, options.select { |k, _| k == '_run_as' })
+      r = executor.file_upload(targets, found, destination, options)
     end
 
     if !r.ok && !options['_catch_errors']

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

@@ -11,17 +11,28 @@ require 'bolt/error'
 #
 Puppet::Functions.create_function(:puppetdb_fact) do
   dispatch :puppetdb_fact do
-    param 'Array[String]', :targets
+    param 'Array[String]', :certnames
+    return_type 'Hash[String, Data]'
   end
 
-  def puppetdb_fact(targets)
+  def puppetdb_fact(certnames)
     unless Puppet[:tasks]
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
         Puppet::Pops::Issues::TASK_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, operation: 'puppetdb_fact'
       )
     end
 
-    executor = Puppet.lookup(:bolt_executor) { nil }
-    executor.puppetdb_fact(targets)
+    puppetdb_client = Puppet.lookup(:bolt_pdb_client) { nil }
+    unless puppetdb_client && Puppet.features.bolt?
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Puppet::Pops::Issues::TASK_MISSING_BOLT, action: _('query facts from puppetdb')
+      )
+    end
+
+    begin
+      puppetdb_client.facts_for_node(certnames)
+    rescue StandardError => e
+      raise Bolt::CLIError, "Could not retrieve targets from PuppetDB: #{e}"
+    end
   end
 end

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

@@ -17,8 +17,22 @@ Puppet::Functions.create_function(:run_command) do
     return_type 'ResultSet'
   end
 
+  dispatch :run_command_with_description do
+    param 'String[1]', :command
+    param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
   def run_command(command, targets, options = nil)
+    run_command_with_description(command, targets, nil, options)
+  end
+
+  def run_command_with_description(command, targets, description = nil, options = nil)
     options ||= {}
+    options = options.merge('_description' => description) if description
+
     unless Puppet[:tasks]
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
         Puppet::Pops::Issues::TASK_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, operation: 'run_command'
@@ -40,7 +54,7 @@ Puppet::Functions.create_function(:run_command) do
       call_function('debug', "Simulating run_command('#{command}') - no targets given - no action taken")
       r = Bolt::ResultSet.new([])
     else
-      r = executor.run_command(targets, command, options.select { |k, _| k == '_run_as' })
+      r = executor.run_command(targets, command, options)
     end
 
     if !r.ok && !options['_catch_errors']

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

@@ -16,8 +16,23 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
     return_type 'ResultSet'
   end
 
+  dispatch :run_script_with_description do
+    scope_param
+    param 'String[1]', :script
+    param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
   def run_script(scope, script, targets, options = nil)
+    run_script_with_description(scope, script, targets, nil, options)
+  end
+
+  def run_script_with_description(scope, script, targets, description = nil, options = nil)
     options ||= {}
+    options = options.merge('_description' => description) if description
+
     unless Puppet[:tasks]
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
         Puppet::Pops::Issues::TASK_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, operation: 'run_script'
@@ -50,7 +65,7 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
     r = if targets.empty?
           Bolt::ResultSet.new([])
         else
-          executor.run_script(targets, found, options['arguments'] || [], options.select { |k, _| k == '_run_as' })
+          executor.run_script(targets, found, options['arguments'] || [], options.reject { |k, _| k == 'arguments' })
         end
 
     if !r.ok && !options['_catch_errors']

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

@@ -10,6 +10,14 @@ require 'bolt/error'
 # * The returned value contains information about the result per target.
 #
 Puppet::Functions.create_function(:run_task) do
+  dispatch :run_task_with_description do
+    param 'String[1]', :task_name
+    param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
+    optional_param 'Hash[String[1], Any]', :task_args
+    return_type 'ResultSet'
+  end
+
   dispatch :run_task do
     param 'String[1]', :task_name
     param 'Boltlib::TargetSpec', :targets
@@ -21,21 +29,26 @@ Puppet::Functions.create_function(:run_task) do
   dispatch :run_task_raw do
     param 'String[1]', :task_name
     param 'Boltlib::TargetSpec', :targets
+    param 'Optional[String]', :description
     optional_param 'Hash[String[1], Any]', :task_args
     # return_type 'ResultSet'
     block_param
   end
 
   def run_task(task_name, targets, task_args = nil)
+    run_task_with_description(task_name, targets, nil, task_args)
+  end
+
+  def run_task_with_description(task_name, targets, description, task_args = nil)
     task_args ||= {}
-    r = run_task_raw(task_name, targets, task_args)
+    r = run_task_raw(task_name, targets, description, task_args)
     if !r.ok && !task_args['_catch_errors']
       raise Bolt::RunFailure.new(r, 'run_task', task_name)
     end
     r
   end
 
-  def run_task_raw(task_name, targets, task_args = nil, &block)
+  def run_task_raw(task_name, targets, description = nil, task_args = nil, &block)
     task_args ||= {}
     unless Puppet[:tasks]
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
@@ -54,7 +67,9 @@ Puppet::Functions.create_function(:run_task) do
     # Ensure that given targets are all Target instances
     targets = inventory.get_targets(targets)
 
-    use_args = task_args.reject { |k, _| k.start_with?('_') }
+    options, use_args = task_args.partition { |k, _| k.start_with?('_') }.map(&:to_h)
+
+    options['_description'] = description if description
 
     # Don't bother loading the local task definition if all targets use the 'pcp' transport
     # and the local-validation option is set to false for all of them
@@ -94,7 +109,6 @@ Puppet::Functions.create_function(:run_task) do
     if targets.empty?
       Bolt::ResultSet.new([])
     else
-      options = task_args.select { |k, _| k == '_run_as' }
       executor.run_task(targets, task, use_args, options, &block)
     end
   end

data/lib/bolt/cli.rb

@@ -16,6 +16,7 @@ require 'bolt/puppetdb'
 require 'bolt/pal'
 require 'bolt/target'
 require 'bolt/version'
+require 'bolt/util/on_access'
 
 module Bolt
   class CLIError < Bolt::Error
@@ -28,11 +29,23 @@ module Bolt
 
   class CLI
     class BoltOptionParser < OptionParser
+      def self.examples(cmd, desc)
+        <<-EXAMP
+#{desc} a Windows host via WinRM, providing for the password
+    bolt #{cmd} -n winrm://winhost -u Administrator -p
+#{desc} the local machine, a Linux host via SSH, and hosts from a group specified in an inventory file
+    bolt #{cmd} -n localhost,nixhost,node_group
+#{desc} Windows hosts queried from PuppetDB via WinRM as a domain user, prompting for the password
+    bolt #{cmd} -q 'inventory[certname] { facts.os.family = "windows" }' --transport winrm -u 'domain\\Administrator' -p
+EXAMP
+      end
+
       BANNER = <<-HELP
 Usage: bolt <subcommand> <action> [options]
 
 Available subcommands:
     bolt command run <command>       Run a command remotely
+    bolt file upload <src> <dest>    Upload a local file
     bolt script run <script>         Upload a local script and run it remotely
     bolt task show                   Show list of available tasks
     bolt task show <task>            Show documentation for task
@@ -40,7 +53,8 @@ Available subcommands:
     bolt plan show                   Show list of available plans
     bolt plan show <plan>            Show details for plan
     bolt plan run <plan> [params]    Run a Puppet task plan
-    bolt file upload <src> <dest>    Upload a local file
+
+Run `bolt <subcommand> --help` to view specific examples.
 
 where [options] are:
       HELP
@@ -55,6 +69,7 @@ Available actions are:
 
 Parameters are of the form <parameter>=<value>.
 
+#{examples('task run facts', 'run facter on')}
 Available options are:
       HELP
 
@@ -64,6 +79,7 @@ Usage: bolt command <action> <command> [options]
 Available actions are:
     run                              Run a command remotely
 
+#{examples('command run hostname', 'run hostname on')}
 Available options are:
       HELP
 
@@ -73,6 +89,7 @@ Usage: bolt script <action> <script> [[arg1] ... [argN]] [options]
 Available actions are:
     run                              Upload a local script and run it remotely
 
+#{examples('script run my_script.ps1 some args', 'run a script on')}
 Available options are:
       HELP
 
@@ -86,6 +103,7 @@ Available actions are:
 
 Parameters are of the form <parameter>=<value>.
 
+#{examples('plan run canary command=hostname', 'run the canary plan on')}
 Available options are:
       HELP
 
@@ -95,6 +113,7 @@ Usage: bolt file <action> [options]
 Available actions are:
     upload <src> <dest>              Upload local file <src> to <dest> on each node
 
+#{examples('file upload /tmp/source /etc/profile.d/login.sh', 'upload a file to')}
 Available options are:
       HELP
 
@@ -119,7 +138,7 @@ Available options are:
                         'Identifies the nodes to target.',
                         'Enter a comma-separated list of node URIs or group names.',
                         "Or read a node list from an input file '@<file>' or stdin '-'.",
-                        'Example: --nodes localhost,node_group,ssh://nix.com:2222,winrm://windows.puppet.com',
+                        'Example: --nodes localhost,node_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(', ')}",
                         'For Windows nodes, specify the winrm:// protocol if it has not be configured',
@@ -127,17 +146,27 @@ Available options are:
                         'For WinRM, port defaults to `5985` or `5986` based on the --[no-]ssl setting') do |nodes|
           @options[:nodes] << get_arg_input(nodes)
         end.extend(SwitchHider)
-        @query = define('-q', '--query QUERY',
-                        'Query PuppetDB to determine the targets') do |query|
+        @query = define('-q', '--query QUERY', 'Query PuppetDB to determine the targets') do |query|
           @options[:query] = query
         end.extend(SwitchHider)
-        define('-u', '--user USER',
-               'User to authenticate as') do |user|
+        define('--noop', 'Execute a task that supports it in noop mode') do |_|
+          @options[:noop] = true
+        end
+        define('--description DESCRIPTION',
+               'Description to use for the job') do |description|
+          @options[:description] = description
+        end
+        define('--params PARAMETERS',
+               "Parameters to a task or plan as json, a json file '@<file>', or on stdin '-'") do |params|
+          @options[:task_options] = parse_params(params)
+        end
+
+        separator 'Authentication:'
+        define('-u', '--user USER', 'User to authenticate as') do |user|
           @options[:user] = user
         end
         define('-p', '--password [PASSWORD]',
-               'Password to authenticate with.',
-               'Omit the value to prompt for the password.') do |password|
+               'Password to authenticate with. Omit the value to prompt for the password.') do |password|
           if password.nil?
             STDOUT.print "Please enter your password: "
             @options[:password] = STDIN.noecho(&:gets).chomp
@@ -146,59 +175,25 @@ Available options are:
             @options[:password] = password
           end
         end
-        define('--private-key KEY',
-               'Private ssh key to authenticate with') do |key|
+        define('--private-key KEY', 'Private ssh key to authenticate with') do |key|
           @options[:'private-key'] = key
         end
-        define('--tmpdir DIR',
-               'The directory to upload and execute temporary files on the target') do |tmpdir|
-          @options[:tmpdir] = tmpdir
-        end
-        define('-c', '--concurrency CONCURRENCY', Integer,
-               'Maximum number of simultaneous connections ' \
-               '(defaults to 100)') do |concurrency|
-          @options[:concurrency] = concurrency
-        end
-        define('--connect-timeout TIMEOUT', Integer,
-               'Connection timeout (defaults vary)') do |timeout|
-          @options[:'connect-timeout'] = timeout
-        end
-        define('--modulepath MODULES',
-               'List of directories containing modules, ' \
-               "separated by '#{File::PATH_SEPARATOR}'") do |modulepath|
-          @options[:modulepath] = modulepath.split(File::PATH_SEPARATOR)
-        end
-        define('--params PARAMETERS',
-               'Parameters to a task or plan') do |params|
-          @options[:task_options] = parse_params(params)
-        end
-
-        define('--format FORMAT',
-               'Output format to use: human or json') do |format|
-          @options[:format] = format
-        end
-        define('--[no-]host-key-check',
-               'Check host keys with SSH') do |host_key_check|
+        define('--[no-]host-key-check', 'Check host keys with SSH') do |host_key_check|
           @options[:'host-key-check'] = host_key_check
         end
-        define('--[no-]ssl',
-               'Use SSL with WinRM') do |ssl|
+        define('--[no-]ssl', 'Use SSL with WinRM') do |ssl|
           @options[:ssl] = ssl
         end
-        define('--[no-]ssl-verify',
-               'Verify remote host SSL certificate with WinRM') do |ssl_verify|
+        define('--[no-]ssl-verify', 'Verify remote host SSL certificate with WinRM') do |ssl_verify|
           @options[:'ssl-verify'] = ssl_verify
         end
-        define('--transport TRANSPORT', TRANSPORTS.keys.map(&:to_s),
-               "Specify a default transport: #{TRANSPORTS.keys.join(', ')}") do |t|
-          @options[:transport] = t
-        end
-        define('--run-as USER',
-               'User to run as using privilege escalation') do |user|
+
+        separator 'Escalation:'
+        define('--run-as USER', 'User to run as using privilege escalation') do |user|
           @options[:'run-as'] = user
         end
         define('--sudo-password [PASSWORD]',
-               'Password for privilege escalation') do |password|
+               'Password for privilege escalation. Omit the value to prompt for the password.') do |password|
           if password.nil?
             STDOUT.print "Please enter your privilege escalation password: "
             @options[:'sudo-password'] = STDIN.noecho(&:gets).chomp
@@ -207,35 +202,57 @@ Available options are:
             @options[:'sudo-password'] = password
           end
         end
-        define('--configfile CONFIG_PATH',
-               'Specify where to load the config file from') do |path|
+
+        separator 'Run context:'
+        define('-c', '--concurrency CONCURRENCY', Integer,
+               'Maximum number of simultaneous connections (default: 100)') do |concurrency|
+          @options[:concurrency] = concurrency
+        end
+        define('--modulepath MODULES',
+               "List of directories containing modules, separated by '#{File::PATH_SEPARATOR}'") do |modulepath|
+          @options[:modulepath] = modulepath.split(File::PATH_SEPARATOR)
+        end
+        define('--configfile FILEPATH',
+               'Specify where to load config from (default: ~/.puppetlabs/bolt.yaml)') do |path|
           @options[:configfile] = path
         end
-        define('--inventoryfile INVENTORY_PATH',
-               'Specify where to load the inventory file from') do |path|
+        define('--inventoryfile FILEPATH',
+               'Specify where to load inventory from (default: ~/.puppetlabs/bolt/inventory.yaml)') do |path|
           if ENV.include?(Bolt::Inventory::ENVIRONMENT_VAR)
             raise Bolt::CLIError, "Cannot pass inventory file when #{Bolt::Inventory::ENVIRONMENT_VAR} is set"
           end
           @options[:inventoryfile] = path
         end
-        define_tail('--[no-]tty',
-                    'Request a pseudo TTY on nodes that support it') do |tty|
+
+        separator 'Transports:'
+        define('--transport TRANSPORT', TRANSPORTS.keys.map(&:to_s),
+               "Specify a default transport: #{TRANSPORTS.keys.join(', ')}") do |t|
+          @options[:transport] = t
+        end
+        define('--connect-timeout TIMEOUT', Integer, 'Connection timeout (defaults vary)') do |timeout|
+          @options[:'connect-timeout'] = timeout
+        end
+        define('--[no-]tty', 'Request a pseudo TTY on nodes that support it') do |tty|
           @options[:tty] = tty
         end
-        define_tail('--noop',
-                    'Execute a task that supports it in noop mode') do |_|
-          @options[:noop] = true
+        define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target') do |tmpdir|
+          @options[:tmpdir] = tmpdir
+        end
+
+        separator 'Display:'
+        define('--format FORMAT', 'Output format to use: human or json') do |format|
+          @options[:format] = format
         end
-        define_tail('-h', '--help', 'Display help') do |_|
+        define('-h', '--help', 'Display help') do |_|
           @options[:help] = true
         end
-        define_tail('--verbose', 'Display verbose logging') do |_|
+        define('--verbose', 'Display verbose logging') do |_|
           @options[:verbose] = true
         end
-        define_tail('--debug', 'Display debug logging') do |_|
+        define('--debug', 'Display debug logging') do |_|
           @options[:debug] = true
         end
-        define_tail('--version', 'Display the version') do |_|
+        define('--version', 'Display the version') do |_|
           puts Bolt::VERSION
           raise Bolt::CLIExit
         end
@@ -449,8 +466,10 @@ Available options are:
 
     def puppetdb_client
       return @puppetdb_client if @puppetdb_client
-      puppetdb_config = Bolt::PuppetDB::Config.new(nil, config.puppetdb)
-      @puppetdb_client = Bolt::PuppetDB::Client.from_config(puppetdb_config)
+      @puppetdb_client = Bolt::Util::OnAccess.new do
+        puppetdb_config = Bolt::PuppetDB::Config.new(nil, config.puppetdb)
+        Bolt::PuppetDB::Client.from_config(puppetdb_config)
+      end
     end
 
     def query_puppetdb_nodes(query)
@@ -511,7 +530,7 @@ Available options are:
           options[:task_options]['nodes'] = options[:nodes].join(',')
         end
         executor = Bolt::Executor.new(config, options[:noop], true)
-        result = pal.run_plan(options[:object], options[:task_options], executor, inventory)
+        result = pal.run_plan(options[:object], options[:task_options], executor, inventory, puppetdb_client)
         outputter.print_plan_result(result)
         # An exception would have been raised if the plan failed
         code = 0
@@ -523,17 +542,19 @@ Available options are:
         outputter.print_head
 
         elapsed_time = Benchmark.realtime do
+          executor_opts = {}
+          executor_opts['_description'] = options[:description] if options.key?(:description)
           results =
             case options[:mode]
             when 'command'
-              executor.run_command(targets, options[:object]) do |event|
+              executor.run_command(targets, options[:object], executor_opts) do |event|
                 outputter.print_event(event)
               end
             when 'script'
               script = options[:object]
               validate_file('script', script)
               executor.run_script(
-                targets, script, options[:leftovers]
+                targets, script, options[:leftovers], executor_opts
               ) do |event|
                 outputter.print_event(event)
               end
@@ -542,7 +563,8 @@ Available options are:
                            targets,
                            options[:task_options],
                            executor,
-                           inventory) do |event|
+                           inventory,
+                           options[:description]) do |event|
                 outputter.print_event(event)
               end
             when 'file'
@@ -553,7 +575,7 @@ Available options are:
                 raise Bolt::CLIError, "A destination path must be specified"
               end
               validate_file('source file', src)
-              executor.file_upload(targets, src, dest) do |event|
+              executor.file_upload(targets, src, dest, executor_opts) do |event|
                 outputter.print_event(event)
               end
             end