bolt 3.3.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e32573bc97fea7eca64b7c915cb4b462e1325fb5d4dcbe95c48c72aae8c0e14
-  data.tar.gz: abb279c5a363092ca37ddf4eac9de665de9f79aa74c9e0af9697910b336b7b93
+  metadata.gz: 575cccb1487a82a6537a83d5d23a89d9e3ed44898af25e2fe34acda2ecd765ae
+  data.tar.gz: a9de53717fdcb5380f95ef5ee1fb26b3d28eaa59f92355d9558954d14192f307
 SHA512:
-  metadata.gz: 23bf7042750c180eb618eaafd8af34e014deb5c7ab0dadcce316e92c3aa66e62ae85e89e96f471cc54f17c81eba463f73b776e9aa4581219567ed15876722967
-  data.tar.gz: bcd1eb6192f5ac92959088edfbe7b333dcb9ed63f6da7a36a6274d72cbce32e77f4f01a8427edec78be3dd9caeab2472ec3691d846108367df407187606ba2ae
+  metadata.gz: 60378d6872763f5fb557deae88207c29db0626d90562e37d80df1f604368629049da79ff0a0216602057566c7eb10892855f33a99b03bfc348fce8b443e7682d
+  data.tar.gz: e2f8dd460e346648e53921e299db5b7beaf4ba1a0cd7efe95728e2e2d42c3e4b3624c40ef8a94a21b7e4be5003d67a1a64c48d1a36a9e314c4d7bb296ce85eab

data/Puppetfile

@@ -6,7 +6,7 @@ moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
 mod 'puppetlabs-service', '2.0.0'
-mod 'puppetlabs-puppet_agent', '4.4.0'
+mod 'puppetlabs-puppet_agent', '4.5.0'
 mod 'puppetlabs-facts', '1.4.0'
 
 # Core types and providers for Puppet 6
@@ -24,17 +24,17 @@ mod 'puppetlabs-zone_core', '1.0.3'
 # Useful additional modules
 mod 'puppetlabs-package', '2.0.0'
 mod 'puppetlabs-powershell_task_helper', '0.1.0'
-mod 'puppetlabs-puppet_conf', '1.0.0'
+mod 'puppetlabs-puppet_conf', '1.1.0'
 mod 'puppetlabs-python_task_helper', '0.5.0'
-mod 'puppetlabs-reboot', '4.0.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', '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-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'

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/puppetdb_command.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Send a command with a payload to PuppetDB.
+#
+# The `pdb_command` function only supports version 5 of the `replace_facts`
+# command. Other commands might also work, but are not tested or supported
+# by Bolt.
+#
+# See the [commands endpoint](https://puppet.com/docs/puppetdb/latest/api/command/v1/commands.html)
+# documentation for more information about available commands and payload
+# format.
+#
+# _This function is experimental and subject to change._
+#
+# > **Note:** Not available in apply block
+#
+Puppet::Functions.create_function(:puppetdb_command) do
+  # @param command The command to invoke.
+  # @param version The version of the command to invoke.
+  # @param payload The payload to the command.
+  # @return The UUID identifying the response sent by PuppetDB.
+  # @example Replace facts for a target
+  #   $payload = {
+  #     'certname'           => 'localhost',
+  #     'environment'        => 'dev',
+  #     'producer'           => 'bolt',
+  #     'producer_timestamp' => '1970-01-01',
+  #     'values'             => { 'orchestrator' => 'bolt' }
+  #   }
+  #
+  #   puppetdb_command('replace_facts', 5, $payload)
+  dispatch :puppetdb_command do
+    param 'String[1]', :command
+    param 'Integer', :version
+    param 'Hash[Data, Data]', :payload
+    return_type 'String'
+  end
+
+  def puppetdb_command(command, version, payload)
+    # Disallow in apply blocks.
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'puppetdb_command'
+      )
+    end
+
+    # Send analytics report.
+    Puppet.lookup(:bolt_executor).report_function_call(self.class.name)
+
+    puppetdb_client = Puppet.lookup(:bolt_pdb_client)
+
+    # Error if the PDB client does not implement :send_command
+    unless puppetdb_client.respond_to?(:send_command)
+      raise Bolt::Error.new(
+        "PuppetDB client #{puppetdb_client.class} does not implement :send_command, "\
+        "unable to invoke command.",
+        'bolt/pdb-command'
+      )
+    end
+
+    puppetdb_client.send_command(command, version, payload)
+  end
+end

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_script.rb

@@ -16,7 +16,7 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
   #   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')
@@ -44,7 +44,7 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
   #   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')
@@ -85,6 +85,23 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
     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)
 

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/prompt/lib/puppet/functions/prompt.rb

@@ -11,12 +11,24 @@ Puppet::Functions.create_function(:prompt) do
   # @option options [Boolean] sensitive Disable echo back and mark the response as sensitive.
   #   The returned value will be wrapped by the `Sensitive` data type. To access the raw
   #   value, use the `unwrap` function (i.e. `$sensitive_value.unwrap`).
+  # @option options [String] default The default value to return if the user does not provide
+  #   input or if stdin is not a tty.
   # @return The response to the prompt.
   # @example Prompt the user if plan execution should continue
   #   $response = prompt('Continue executing plan? [Y\N]')
   # @example Prompt the user for sensitive information
   #   $password = prompt('Enter your password', 'sensitive' => true)
   #   out::message("Password is: ${password.unwrap}")
+  # @example Prompt the user and provide a default value
+  #   $user = prompt('Enter your login username', 'default' => 'root')
+  # @example Prompt the user for sensitive information, returning a sensitive default if one is not provided
+  #   $token = prompt('Enter token', 'default' => lookup('default_token'), 'sensitive' => true)
+  #   out::message("Token is: ${token.unwrap}")
+  # @example Prompt the user and fail with a custom message if no input was provided
+  #   $response = prompt('Enter your name', 'default' => '')
+  #   if $response.empty {
+  #     fail_plan('Must provide your name')
+  #   }
   dispatch :prompt do
     param 'String', :prompt
     optional_param 'Hash[String[1], Any]', :options
@@ -30,14 +42,20 @@ Puppet::Functions.create_function(:prompt) do
                               action: 'prompt')
     end
 
-    options = options.transform_keys(&:to_sym)
-
+    options  = options.transform_keys(&:to_sym)
     executor = Puppet.lookup(:bolt_executor)
+
     # Send analytics report
     executor.report_function_call(self.class.name)
 
+    # Require default to be a string value
+    if options.key?(:default) && !options[:default].is_a?(String)
+      raise Bolt::ValidationError, "Option 'default' must be a string"
+    end
+
     response = executor.prompt(prompt, options)
 
+    # If sensitive, wrap it
     if options[:sensitive]
       Puppet::Pops::Types::PSensitiveType::Sensitive.new(response)
     else