bolt 3.0.1 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16ea129b96b72ea751f0b59599b8783c7c2ad45ebc46004058384693d71795f1
-  data.tar.gz: 9f227b4c8a2fbe06410090adb6590ddce9e8f4ae29a2fa10f0e2e464fa166c0a
+  metadata.gz: aa3e5ea7d868b032557568e9635fcf159f00b81e4961dce4032246cc150a7c16
+  data.tar.gz: 0e9fada8a0518ab174412e21ec843091272cb0afe87980703ebd6d8ed91002dd
 SHA512:
-  metadata.gz: 8c6c1b341c1b8d83ec37184a2a9875e0665e4b5a1ed2a6b0c58266b38a541cafffb89df39da659a6ee6157a4140db852d43fa104b3ed7d99400011ec624139a7
-  data.tar.gz: 7f9a485096374549f2d5f29ff00954c810016c751f54d551c9367212ccf889eced3b71a13e262ebd6916ad2568139298b87081412ef96d091aeddeffbb924684
+  metadata.gz: 66d8df12e0142b6d5872a40f7c0d97b0438c833e4681be6646e17b85496c3a9e1148ff0a2ff34572e0ce788861d928c406dddcb97feb5281ac0d7eb2d7d14ead
+  data.tar.gz: f6dafaa37a4af7633610e26cc084d69c865f0b8df18221d407f2ee077e58e0a582e88cccf49d3a590e7984d56d8ac467ee8704e6ac0e60cc7e37b1a846396d26

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.6.0'
+mod 'puppetlabs-stdlib', '7.0.0'
 
 # Plugin modules
-mod 'puppetlabs-aws_inventory', '0.6.0'
+mod 'puppetlabs-aws_inventory', '0.7.0'
 mod 'puppetlabs-azure_inventory', '0.5.0'
-mod 'puppetlabs-gcloud_inventory', '0.2.0'
-mod 'puppetlabs-http_request', '0.2.1'
+mod 'puppetlabs-gcloud_inventory', '0.3.0'
+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/datatypes/containerresult.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+Puppet::DataTypes.create_type('ContainerResult') do
+  interface <<-PUPPET
+    attributes => {
+      'value' => Hash[String[1], Data],
+    },
+    functions => {
+      '[]' => Callable[[String[1]], Data],
+      error => Callable[[], Optional[Error]],
+      ok => Callable[[], Boolean],
+      status => Callable[[], String],
+      stdout => Callable[[], String],
+      stderr => Callable[[], String],
+      to_data => Callable[[], Hash]
+    }
+  PUPPET
+
+  load_file('bolt/container_result')
+
+  # Needed for Puppet to recognize Bolt::ContainerResult as a Puppet object when deserializing
+  Bolt::ContainerResult.include(Puppet::Pops::Types::PuppetObject)
+  implementation_class Bolt::ContainerResult
+end

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_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_container.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'bolt/container_result'
+require 'bolt/error'
+require 'bolt/util'
+
+# Run a container and return its output to stdout and stderr.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:run_container) do
+  # Run a container.
+  # @param image The name of the image to run.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] cmd A command to run in the container.
+  # @option options [Hash[String, Data]] env_vars Map of environment variables to set.
+  # @option options [Hash[Integer, Integer]] ports A map of container ports to
+  #   publish. Keys are the host port, values are the corresponding container
+  #   port.
+  # @option options [Boolean] rm Whether to remove the container once it exits.
+  # @option options [Hash[String, String]] volumes A map of absolute paths on
+  #   the host to absolute paths on the remote to mount.
+  # @option options [String] workdir The working directory within the container.
+  # @return Output from the container.
+  # @example Run Nginx proxy manager
+  #   run_container('jc21/nginx-proxy-manager', 'ports' => { 80 => 80, 81 => 81, 443 => 443 })
+  dispatch :run_container do
+    param 'String[1]', :image
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ContainerResult'
+  end
+
+  def run_container(image, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'run_container')
+    end
+
+    # Send Analytics Report
+    executor = Puppet.lookup(:bolt_executor)
+    executor.report_function_call(self.class.name)
+
+    options = options.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    validate_options(options)
+
+    if options.key?(:env_vars)
+      options[:env_vars] = options[:env_vars].transform_values do |val|
+        [Array, Hash].include?(val.class) ? val.to_json : val
+      end
+    end
+
+    if options[:ports]
+      ports = options[:ports].each_with_object([]) do |(host_port, container_port), acc|
+        acc << "-p"
+        acc << "#{host_port}:#{container_port}"
+      end
+    end
+
+    if options[:volumes]
+      volumes = options[:volumes].each_with_object([]) do |(host_path, remote_path), acc|
+        begin
+          FileUtils.mkdir_p(host_path)
+        rescue StandardError => e
+          message = "Unable to create host volume directory #{host_path}: #{e.message}"
+          raise Bolt::Error.new(message, 'bolt/file-error')
+        end
+        acc << "-v"
+        acc << "#{host_path}:#{remote_path}"
+      end
+    end
+
+    # Run the container
+    # `docker run` will automatically pull the image if it isn't already downloaded
+    cmd = %w[run]
+    cmd += Bolt::Util.format_env_vars_for_cli(options[:env_vars]) if options[:env_vars]
+    cmd += volumes if volumes
+    cmd += ports if ports
+    cmd << "--rm" if options[:rm]
+    cmd += %W[-w #{options[:workdir]}] if options[:workdir]
+    cmd << image
+    cmd += Shellwords.shellsplit(options[:cmd]) if options[:cmd]
+
+    executor.publish_event(type: :container_start, image: image)
+    out, err, status = Bolt::Util.exec_docker(cmd)
+
+    o = out.is_a?(String) ? out.dup.force_encoding('utf-8') : out
+    e = err.is_a?(String) ? err.dup.force_encoding('utf-8') : err
+
+    unless status.exitstatus.zero?
+      result = Bolt::ContainerResult.from_exception(e,
+                                                    status.exitstatus,
+                                                    image,
+                                                    position: Puppet::Pops::PuppetStack.top_of_stack)
+      executor.publish_event(type: :container_finish, result: result)
+      if options[:catch_errors]
+        return result
+      else
+        raise Bolt::ContainerFailure, result
+      end
+    end
+
+    value = { 'stdout' => o, 'stderr' => e, 'exit_code' => status.exitstatus }
+    result = Bolt::ContainerResult.new(value, object: image)
+    executor.publish_event(type: :container_finish, result: result)
+    result
+  end
+
+  def validate_options(options)
+    if options.key?(:env_vars)
+      ev = options[:env_vars]
+      unless ev.is_a?(Hash)
+        msg = "Option 'env_vars' must be a hash. Received #{ev} which is a #{ev.class}"
+        raise Bolt::ValidationError, msg
+      end
+
+      if (bad_keys = ev.keys.reject { |k| k.is_a?(String) }).any?
+        msg = "Keys for option 'env_vars' must be strings: #{bad_keys.map(&:inspect).join(', ')}"
+        raise Bolt::ValidationError, msg
+      end
+    end
+
+    if options.key?(:volumes)
+      volumes = options[:volumes]
+      unless volumes.is_a?(Hash)
+        msg = "Option 'volumes' must be a hash. Received #{volumes} which is a #{volumes.class}"
+        raise Bolt::ValidationError, msg
+      end
+
+      if (bad_vs = volumes.reject { |k, v| k.is_a?(String) && v.is_a?(String) }).any?
+        msg = "Option 'volumes' only accepts strings for keys and values. "\
+          "Received: #{bad_vs.map(&:inspect).join(', ')}"
+        raise Bolt::ValidationError, msg
+      end
+    end
+
+    if options.key?(:cmd) && !options[:cmd].is_a?(String)
+      cmd = options[:cmd]
+      msg = "Option 'cmd' must be a string. Received #{cmd} which is a #{cmd.class}"
+      raise Bolt::ValidationError, msg
+    end
+
+    if options.key?(:workdir) && !options[:workdir].is_a?(String)
+      wd = options[:workdir]
+      msg = "Option 'workdir' must be a string. Received #{wd} which is a #{wd.class}"
+      raise Bolt::ValidationError, msg
+    end
+
+    if options.key?(:ports)
+      ports = options[:ports]
+      unless ports.is_a?(Hash)
+        msg = "Option 'ports' must be a hash. Received #{ports} which is a #{ports.class}"
+        raise Bolt::ValidationError, msg
+      end
+
+      if (bad_ps = ports.reject { |k, v| k.is_a?(Integer) && v.is_a?(Integer) }).any?
+        msg = "Option 'ports' only accepts integers for keys and values. "\
+          "Received: #{bad_ps.map(&:inspect).join(', ')}"
+        raise Bolt::ValidationError, msg
+      end
+    end
+  end
+end

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/types/planresult.pp

@@ -12,5 +12,6 @@ type Boltlib::PlanResult = Variant[Boolean,
                                    ResultSet,
                                    Target,
                                    ResourceInstance,
+                                   ContainerResult,
                                    Array[Boltlib::PlanResult],
                                    Hash[String, Boltlib::PlanResult]]

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