bolt 3.0.0 → 3.5.0

data/lib/bolt/config/transport/lxd.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class LXD < Base
+        OPTIONS = %w[
+          cleanup
+          remote
+          tmpdir
+        ].freeze
+
+        DEFAULTS = {
+          'cleanup' => true,
+          'remote'  => 'local'
+        }.freeze
+      end
+    end
+  end
+end

data/lib/bolt/config/transport/options.rb

@@ -32,7 +32,7 @@ module Bolt
           "cleanup" => {
             type: [TrueClass, FalseClass],
             description: "Whether to clean up temporary files created on targets. When running commands on a target, "\
-                         "Bolt may create temporary files. After completing the command, these files are "\
+                         "Bolt might create temporary files. After completing the command, these files are "\
                          "automatically deleted. This value can be set to 'false' if you wish to leave these "\
                          "temporary files on the target.",
             _plugin: true,
@@ -266,6 +266,13 @@ module Bolt
             _plugin: true,
             _example: "BOLT.PRODUCTION"
           },
+          "remote" => {
+            type: String,
+            description: "The LXD remote host to use.",
+            _default: "local",
+            _plugin: false,
+            _example: 'myremote'
+          },
           "run-as" => {
             type: String,
             description: "The user to run commands as after login. The run-as user must be different than the "\

data/lib/bolt/container_result.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'bolt/error'
+require 'bolt/result'
+
+module Bolt
+  class ContainerResult
+    attr_reader :value, :object
+
+    def self.from_exception(exception, exit_code, image, position: [])
+      details = Bolt::Result.create_details(position)
+      error = {
+        'kind' => 'puppetlabs.tasks/container-error',
+        'issue_code' => 'CONTAINER_ERROR',
+        'msg' => "Error running container '#{image}': #{exception}",
+        'details' => details
+      }
+      error['details']['exit_code'] = exit_code
+      ContainerResult.new({ '_error' => error }, object: image)
+    end
+
+    def _pcore_init_hash
+      { 'value' => @value,
+        'object' => @image }
+    end
+
+    # First argument can't be named given the way that Puppet deserializes variables
+    def initialize(value = nil, object: nil)
+      @value = value || {}
+      @object = object
+    end
+
+    def eql?(other)
+      self.class == other.class &&
+        value == other.value
+    end
+    alias == eql?
+
+    def [](key)
+      value[key]
+    end
+
+    def to_json(opts = nil)
+      to_data.to_json(opts)
+    end
+    alias to_s to_json
+
+    # This is the value with all non-UTF-8 characters removed, suitable for
+    # printing or converting to JSON. It *should* only be possible to have
+    # non-UTF-8 characters in stdout/stderr keys as they are not allowed from
+    # tasks but we scrub the whole thing just in case.
+    def safe_value
+      Bolt::Util.walk_vals(value) do |val|
+        if val.is_a?(String)
+          # Replace invalid bytes with hex codes, ie. \xDE\xAD\xBE\xEF
+          val.scrub { |c| c.bytes.map { |b| "\\x" + b.to_s(16).upcase }.join }
+        else
+          val
+        end
+      end
+    end
+
+    def stdout
+      value['stdout']
+    end
+
+    def stderr
+      value['stderr']
+    end
+
+    def to_data
+      {
+        "object" => object,
+        "status" => status,
+        "value" => safe_value
+      }
+    end
+
+    def status
+      ok? ? 'success' : 'failure'
+    end
+
+    def ok?
+      error_hash.nil?
+    end
+    alias ok ok?
+    alias success? ok?
+
+    # This allows access to errors outside puppet compilation
+    # it should be prefered over error in bolt code
+    def error_hash
+      value['_error']
+    end
+
+    # Warning: This will fail outside of a compilation.
+    # Use error_hash inside bolt.
+    # Is it crazy for this to behave differently outside a compiler?
+    def error
+      if error_hash
+        Puppet::DataTypes::Error.from_asserted_hash(error_hash)
+      end
+    end
+  end
+end

data/lib/bolt/error.rb

@@ -61,6 +61,21 @@ module Bolt
     end
   end
 
+  class ContainerFailure < Bolt::Error
+    attr_reader :result
+
+    def initialize(result)
+      details = {
+        'value' => result.value,
+        'object' => result.object
+      }
+      message = "Plan aborted: Running container '#{result.object}' failed."
+      super(message, 'bolt/container-failure', details)
+      @result = result
+      @error_code = 2
+    end
+  end
+
   class RunFailure < Bolt::Error
     attr_reader :result_set
 

data/lib/bolt/executor.rb

@@ -4,6 +4,7 @@
 require 'English'
 require 'json'
 require 'logging'
+require 'pathname'
 require 'set'
 require 'bolt/analytics'
 require 'bolt/result'
@@ -15,6 +16,7 @@ require 'bolt/transport/ssh'
 require 'bolt/transport/winrm'
 require 'bolt/transport/orch'
 require 'bolt/transport/local'
+require 'bolt/transport/lxd'
 require 'bolt/transport/docker'
 require 'bolt/transport/remote'
 require 'bolt/yarn'
@@ -25,6 +27,7 @@ module Bolt
     winrm: Bolt::Transport::WinRM,
     pcp: Bolt::Transport::Orch,
     local: Bolt::Transport::Local,
+    lxd: Bolt::Transport::LXD,
     docker: Bolt::Transport::Docker,
     remote: Bolt::Transport::Remote
   }.freeze
@@ -39,7 +42,6 @@ module Bolt
                    modified_concurrency = false)
       # lazy-load expensive gem code
       require 'concurrent'
-
       @analytics = analytics
       @logger = Bolt::Logger.logger(self)
 
@@ -121,8 +123,8 @@ module Bolt
     def queue_execute(targets)
       if @warn_concurrency && targets.length > @concurrency
         @warn_concurrency = false
-        msg = "The ulimit is low, which may cause file limit issues. Default concurrency has been set to "\
-              "'#{@concurrency}' to mitigate those issues, which may cause Bolt to run slow. "\
+        msg = "The ulimit is low, which might cause file limit issues. Default concurrency has been set to "\
+              "'#{@concurrency}' to mitigate those issues, which might cause Bolt to run slow. "\
               "Disable this warning by configuring ulimit using 'ulimit -n <limit>' in your shell "\
               "configuration, or by configuring Bolt's concurrency. "\
               "See https://puppet.com/docs/bolt/latest/bolt_known_issues.html for details."
@@ -215,7 +217,7 @@ module Bolt
       results
     end
 
-    def report_transport(transport, count)
+    private def report_transport(transport, count)
       name = transport.class.name.split('::').last.downcase
       unless @reported_transports.include?(name)
         @analytics&.event('Transport', 'initialize', label: name, value: count)
@@ -231,6 +233,11 @@ module Bolt
       @analytics.report_bundled_content(mode, name)
     end
 
+    def report_file_source(plan_function, source)
+      label = Pathname.new(source).absolute? ? 'absolute' : 'module'
+      @analytics&.event('Plan', plan_function, label: label)
+    end
+
     def report_apply(statement_count, resource_counts)
       data = { statement_count: statement_count }
 
@@ -468,7 +475,7 @@ module Bolt
       Time.now
     end
 
-    def wait_until(timeout, retry_interval)
+    private def wait_until(timeout, retry_interval)
       start = wait_now
       until yield
         raise(TimeoutError, 'Timed out waiting for target') if (wait_now - start).to_i >= timeout
@@ -477,22 +484,30 @@ module Bolt
     end
 
     def prompt(prompt, options)
-      @prompting = true
       unless $stdin.tty?
+        return options[:default] if options[:default]
         raise Bolt::Error.new('STDIN is not a tty, unable to prompt', 'bolt/no-tty-error')
       end
 
-      $stderr.print("#{prompt}: ")
+      @prompting = true
+
+      if options[:default] && !options[:sensitive]
+        $stderr.print("#{prompt} [#{options[:default]}]: ")
+      else
+        $stderr.print("#{prompt}: ")
+      end
 
       value = if options[:sensitive]
                 $stdin.noecho(&:gets).to_s.chomp
               else
                 $stdin.gets.to_s.chomp
               end
+
       @prompting = false
 
       $stderr.puts if options[:sensitive]
 
+      value = options[:default] if value.empty?
       value
     end
 

data/lib/bolt/inventory/options.rb

@@ -11,8 +11,10 @@ module Bolt
         facts
         features
         groups
+        plugin_hooks
         targets
         vars
+        version
       ].freeze
 
       # Definitions used to validate the data.
@@ -123,6 +125,13 @@ module Bolt
           description: "A map of variables for the group or target.",
           type: Hash,
           _plugin: true
+        },
+        "version" => {
+          description: "The version of the inventory file.",
+          type: Integer,
+          _plugin: false,
+          _example: 2,
+          _default: 2
         }
       }.freeze
     end

data/lib/bolt/inventory/target.rb

@@ -92,6 +92,7 @@ module Bolt
       end
 
       def add_facts(new_facts = {})
+        validate_fact_names(new_facts)
         @facts = Bolt::Util.deep_merge(@facts, new_facts)
       end
 
@@ -153,9 +154,24 @@ module Bolt
           raise Bolt::UnknownTransportError.new(transport, uri)
         end
 
+        validate_fact_names(facts)
+
         transport_config
       end
 
+      # Validate fact names and issue a deprecation warning if any fact names have a dot.
+      #
+      private def validate_fact_names(facts)
+        if (dotted = facts.keys.select { |name| name.include?('.') }).any?
+          Bolt::Logger.deprecate(
+            'dotted_fact_name',
+            "Target '#{safe_name}' includes dotted fact names: '#{dotted.join("', '")}'. Dotted fact "\
+            "names are deprecated and Bolt does not automatically convert facts with dotted names to "\
+            "structured facts. For more information, see https://pup.pt/bolt-dotted-facts"
+          )
+        end
+      end
+
       def host
         @uri_obj.hostname || transport_config['host']
       end

data/lib/bolt/logger.rb

@@ -91,6 +91,14 @@ module Bolt
       Logging.logger[:root].appenders.any?
     end
 
+    def self.stream
+      @stream
+    end
+
+    def self.stream=(stream)
+      @stream = stream
+    end
+
     # A helper to ensure the Logging library is always initialized with our
     # custom log levels before retrieving a Logger instance.
     def self.logger(name)

data/lib/bolt/module_installer.rb

@@ -45,7 +45,7 @@ module Bolt
       # specss. If that fails, fall back to resolving from project specs.
       # This prevents Bolt from modifying installed modules unless there is
       # a version conflict.
-      @outputter.print_action_step("Resolving module dependencies, this may take a moment")
+      @outputter.print_action_step("Resolving module dependencies, this might take a moment")
 
       @outputter.start_spin
       begin
@@ -156,7 +156,7 @@ module Bolt
         # If forcibly installing or if there is no Puppetfile, resolve
         # and write a Puppetfile.
         if force || !path.exist?
-          @outputter.print_action_step("Resolving module dependencies, this may take a moment")
+          @outputter.print_action_step("Resolving module dependencies, this might take a moment")
 
           # This doesn't use the block as it's more testable to just mock *_spin
           @outputter.start_spin

data/lib/bolt/module_installer/puppetfile.rb

@@ -36,7 +36,7 @@ module Bolt
           raise Bolt::ValidationError, <<~MSG
             Unable to parse Puppetfile #{path}:
             #{parsed.validation_errors.join("\n\n")}.
-            This may not be a Puppetfile managed by Bolt.
+            This Puppetfile might not be managed by Bolt.
           MSG
         end
 
@@ -106,7 +106,7 @@ module Bolt
 
           #{unsatisfied_specs.map(&:to_hash).to_yaml.lines.drop(1).join.chomp}
           
-          This may not be a Puppetfile managed by Bolt. To forcibly overwrite the
+          This Puppetfile might not be managed by Bolt. To forcibly overwrite the
           Puppetfile, run '#{command}'.
         MESSAGE
 

data/lib/bolt/module_installer/specs/forge_spec.rb

@@ -39,8 +39,8 @@ module Bolt
           unless (match = name.match(NAME_REGEX))
             raise Bolt::ValidationError,
                   "Invalid name for Forge module specification: #{name}. Name must match "\
-                  "'owner/name'. Owner segment may only include letters or digits. Name "\
-                  "segment must start with a lowercase letter and may only include lowercase "\
+                  "'owner/name'. Owner segment can only include letters or digits. Name "\
+                  "segment must start with a lowercase letter and can only include lowercase "\
                   "letters, digits, and underscores."
           end
 

data/lib/bolt/module_installer/specs/git_spec.rb

@@ -49,8 +49,8 @@ module Bolt
           unless (match = name.match(NAME_REGEX))
             raise Bolt::ValidationError,
                   "Invalid name for Git module specification: #{name}. Name must match "\
-                  "'name' or 'owner/name'. Owner segment may only include letters or digits. "\
-                  "Name segment must start with a lowercase letter and may only include "\
+                  "'name' or 'owner/name'. Owner segment can only include letters or digits. "\
+                  "Name segment must start with a lowercase letter and can only include "\
                   "lowercase letters, digits, and underscores."
           end
 

data/lib/bolt/node/output.rb

@@ -6,13 +6,23 @@ require 'bolt/result'
 module Bolt
   class Node
     class Output
-      attr_reader :stdout, :stderr
+      attr_reader :stderr, :stdout, :merged_output
       attr_accessor :exit_code
 
       def initialize
-        @stdout = StringIO.new
-        @stderr = StringIO.new
-        @exit_code = 'unknown'
+        @stdout        = StringIO.new
+        @stderr        = StringIO.new
+        @merged_output = StringIO.new
+        @exit_code     = 'unknown'
+      end
+
+      def to_h
+        {
+          'stdout'        => @stdout.string,
+          'stderr'        => @stderr.string,
+          'merged_output' => @merged_output.string,
+          'exit_code'     => @exit_code
+        }
       end
     end
   end

data/lib/bolt/outputter/human.rb

@@ -53,10 +53,21 @@ module Bolt
         string.sub(/\s\z/, '')
       end
 
+      # Wraps a string to the specified width. Lines only wrap
+      # at whitespace.
+      #
       def wrap(string, width = 80)
+        return string unless string.is_a?(String)
         string.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n")
       end
 
+      # Trims a string to a specified width, adding an ellipsis if it's longer.
+      #
+      def truncate(string, width = 80)
+        return string unless string.is_a?(String) && string.length > width
+        string.lines.first[0...width].gsub(/\s\w+\s*$/, '...')
+      end
+
       def handle_event(event)
         case event[:type]
         when :enable_default_output
@@ -81,6 +92,10 @@ module Bolt
             print_plan_start(event)
           when :plan_finish
             print_plan_finish(event)
+          when :container_start
+            print_container_start(event) if plan_logging?
+          when :container_finish
+            print_container_finish(event) if plan_logging?
           when :start_spin
             start_spin
           when :stop_spin
@@ -101,6 +116,34 @@ module Bolt
         @stream.puts(colorize(:green, "Started on #{target.safe_name}..."))
       end
 
+      def print_container_result(result)
+        if result.success?
+          @stream.puts(colorize(:green, "Finished running container #{result.object}:"))
+        else
+          @stream.puts(colorize(:red, "Failed running container #{result.object}:"))
+        end
+
+        if result.error_hash
+          @stream.puts(colorize(:red, remove_trail(indent(2, result.error_hash['msg']))))
+          return 0
+        end
+
+        # Only print results if there's something other than empty string and hash
+        safe_value = result.safe_value
+        if safe_value['stdout'].strip.empty? && safe_value['stderr'].strip.empty?
+          @stream.puts(indent(2, "Running container #{result.object} completed successfully with no result"))
+        else
+          unless safe_value['stdout'].strip && safe_value['stdout'].strip.empty?
+            @stream.puts(indent(2, "STDOUT:"))
+            @stream.puts(indent(4, safe_value['stdout']))
+          end
+          unless safe_value['stderr'].strip.empty?
+            @stream.puts(indent(2, "STDERR:"))
+            @stream.puts(indent(4, safe_value['stderr']))
+          end
+        end
+      end
+
       def print_result(result)
         if result.success?
           @stream.puts(colorize(:green, "Finished on #{result.target.safe_name}:"))
@@ -131,16 +174,9 @@ module Bolt
           end
 
           # Use special handling if the result looks like a command or script result
-          if result.generic_value.keys == %w[stdout stderr exit_code]
+          if result.generic_value.keys == %w[stdout stderr merged_output exit_code]
             safe_value = result.safe_value
-            unless safe_value['stdout'].strip.empty?
-              @stream.puts(indent(2, "STDOUT:"))
-              @stream.puts(indent(4, safe_value['stdout']))
-            end
-            unless safe_value['stderr'].strip.empty?
-              @stream.puts(indent(2, "STDERR:"))
-              @stream.puts(indent(4, safe_value['stderr']))
-            end
+            @stream.puts(indent(2, safe_value['merged_output'])) unless safe_value['merged_output'].strip.empty?
           elsif result.generic_value.any?
             @stream.puts(indent(2, ::JSON.pretty_generate(result.generic_value)))
           end
@@ -176,6 +212,25 @@ module Bolt
         @stream.puts(colorize(:green, message))
       end
 
+      def print_container_start(image:, **_kwargs)
+        @stream.puts(colorize(:green, "Starting: run container '#{image}'"))
+      end
+
+      def print_container_finish(event)
+        result = if event[:result].is_a?(Bolt::ContainerFailure)
+                   event[:result].result
+                 else
+                   event[:result]
+                 end
+
+        if result.success?
+          @stream.puts(colorize(:green, "Finished: run container '#{result.object}' succeeded."))
+        else
+          @stream.puts(colorize(:red, "Finished: run container '#{result.object}' failed."))
+        end
+        print_container_result(result) if @verbose
+      end
+
       def print_plan_start(event)
         @plan_depth += 1
         # We use this event to both mark the start of a plan _and_ to enable
@@ -218,11 +273,11 @@ module Bolt
         @stream.puts total_msg
       end
 
-      def print_table(results, padding_left = 0, padding_right = 3)
+      def format_table(results, padding_left = 0, padding_right = 3)
         # lazy-load expensive gem code
         require 'terminal-table'
 
-        @stream.puts Terminal::Table.new(
+        Terminal::Table.new(
           rows: results,
           style: {
             border_x: '',
@@ -238,10 +293,22 @@ module Bolt
 
       def print_tasks(tasks, modulepath)
         command = Bolt::Util.powershell? ? 'Get-BoltTask -Task <TASK NAME>' : 'bolt task show <TASK NAME>'
-        tasks.any? ? print_table(tasks) : print_message('No available tasks')
-        print_message("\nMODULEPATH:\n#{modulepath.join(File::PATH_SEPARATOR)}\n"\
-                        "\nUse '#{command}' to view "\
-                        "details and parameters for a specific task.")
+
+        tasks = tasks.map do |name, description|
+          description = truncate(description, 72)
+          [name, description]
+        end
+
+        @stream.puts colorize(:cyan, 'Tasks')
+        @stream.puts tasks.any? ? format_table(tasks, 2) : indent(2, 'No available tasks')
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Modulepath')
+        @stream.puts indent(2, modulepath.join(File::PATH_SEPARATOR))
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Additional information')
+        @stream.puts indent(2, "Use '#{command}' to view details and parameters for a specific task.")
       end
 
       # @param [Hash] task A hash representing the task
@@ -259,7 +326,7 @@ module Bolt
           pretty_params << "- #{k}: #{v['type'] || 'Any'}\n"
           pretty_params << "    Default: #{v['default'].inspect}\n" if v.key?('default')
           pretty_params << "    #{v['description']}\n" if v['description']
-          usage << if v['type'].start_with?("Optional")
+          usage << if v['type']&.start_with?("Optional")
                      " [#{k}=<value>]"
                    else
                      " #{k}=<value>"
@@ -267,7 +334,7 @@ module Bolt
         end
 
         if task.supports_noop
-          usage << Bolt::Util.powershell? ? '[-Noop]' : '[--noop]'
+          usage << (Bolt::Util.powershell? ? ' [-Noop]' : ' [--noop]')
         end
 
         task_info << "\n#{task.name}"
@@ -322,10 +389,22 @@ module Bolt
 
       def print_plans(plans, modulepath)
         command = Bolt::Util.powershell? ? 'Get-BoltPlan -Name <PLAN NAME>' : 'bolt plan show <PLAN NAME>'
-        plans.any? ? print_table(plans) : print_message('No available plans')
-        print_message("\nMODULEPATH:\n#{modulepath.join(File::PATH_SEPARATOR)}\n"\
-                        "\nUse '#{command}' to view "\
-                        "details and parameters for a specific plan.")
+
+        plans = plans.map do |name, description|
+          description = truncate(description, 72)
+          [name, description]
+        end
+
+        @stream.puts colorize(:cyan, 'Plans')
+        @stream.puts plans.any? ? format_table(plans, 2) : indent(2, 'No available plans')
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Modulepath')
+        @stream.puts indent(2, modulepath.join(File::PATH_SEPARATOR))
+        @stream.puts
+
+        @stream.puts colorize(:cyan, 'Additional information')
+        @stream.puts indent(2, "Use '#{command}' to view details and parameters for a specific plan.")
       end
 
       def print_topics(topics)
@@ -359,7 +438,7 @@ module Bolt
               [m[:name], version]
             end
 
-            print_table(module_info, 2, 1)
+            @stream.puts format_table(module_info, 2, 1)
           end
 
           @stream.write("\n")
@@ -374,7 +453,7 @@ module Bolt
         targets += target_list[:adhoc].map { |target| [target.name, adhoc] }
 
         if targets.any?
-          print_table(targets, 0, 2)
+          @stream.puts format_table(targets, 0, 2)
           @stream.puts
         end
 
@@ -417,6 +496,10 @@ module Bolt
           @stream.puts("Plan completed successfully with no result")
         when Bolt::ApplyFailure, Bolt::RunFailure
           print_result_set(value.result_set)
+        when Bolt::ContainerResult
+          print_container_result(value)
+        when Bolt::ContainerFailure
+          print_container_result(value.result)
         when Bolt::ResultSet
           print_result_set(value)
         else