bolt 3.4.0 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e66e28078af9324bb7d5668ee5079535d829913a2dcb4bce65daa4d471d4524
-  data.tar.gz: a821d82c490030be200c0d4ab5dc4a56a1abf1aa862d69d1e4c6a4595e47952d
+  metadata.gz: 741f798df2b4c7a46e45c5c87a41cd4e994506cdd202d26b6acafae7774135f8
+  data.tar.gz: 803789a5f6872e27656a733e94998acc9dde4d325d2d920b345a1c2848683f2f
 SHA512:
-  metadata.gz: 120dd18c9478c105387f2ad3634276cbaae05fe3638cc01d378aa9cbb1c423bf737991b7278ab4f96eb0a7cca39cd3d259cbba3d1734cea6ac071ba0695da901
-  data.tar.gz: 61171ff383d06883e6f6ffa0cafc423a80d41ea0f2d45c3c0e4b76c7037a4626ad7a4b8b625e3a013e077b9e96cdafaab06cad6d5a490dae392af3fbb410d0fe
+  metadata.gz: 85cb83b0a0bf02d1ba15b14ba5e5e75c6ff290e1acee71b0de06ea716f3698e91358aa6f9961757b088afa3c98d519ba10f79a6195c767492a87603759c2fc81
+  data.tar.gz: 8180f0827c3576e676e6fca59af7744d3e375023b44c0ebc2e691801a25f8fc1cac2487276661f7b40503e8ab1164ae07ee5f8343be9bb5be3088851e81eafaf

data/Puppetfile

@@ -32,9 +32,9 @@ 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/applyresult.rb

@@ -1,5 +1,31 @@
 # frozen_string_literal: true
 
+# An [apply action](applying_manifest_blocks.md#return-value-of-apply-action)
+# returns an `ApplyResult`. An `ApplyResult` is part of a `ResultSet` object and
+# contains information about the apply action.
+#
+# @param report
+#   The Puppet report from the apply action. Equivalent to calling `ApplyResult.value['report']`.
+#   The report is a hash representation of the [`Puppet::Transaction::Report`
+#   object](https://puppet.com/docs/puppet/latest/format_report.html), where each property
+#   corresponds to a key in the report hash. For more information, see [Result
+#   keys](applying_manifest_blocks.md#result-keys).
+# @param target
+#   The target the result is from.
+#
+# @!method action
+#   The action performed. `ApplyResult.action` always returns the string `apply`.
+# @!method error
+#   Returns an Error object constructed from the `_error` field of the result's value.
+# @!method message
+#   The `_output` field of the result's value.
+# @!method ok
+#   Whether the result was successful.
+# @!method to_data
+#   A serialized representation of `ApplyResult`.
+# @!method value
+#   A hash including the Puppet report from the apply action under a `report` key.
+#
 Puppet::DataTypes.create_type('ApplyResult') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/containerresult.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# The [run_container](plan_functions.md#run_container) plan function returns a
+# `ContainerResult` object. A `ContainerResult` is a standalone object (not part
+# of a `ResultSet`) that includes either the `stdout` and `stderr` values from
+# running the container, or an `_error` object if the container exited with a
+# nonzero exit code.
+#
+# @param value
+#   A hash including the `stdout`, `stderr`, and `exit_code` received from the
+#   container.
+#
+# @!method []
+#   Accesses the value hash directly and returns the value for the key. This
+#   function does not use dot notation. Call the function directly on the
+#   `ContainerResult`. For example, `$result[key]`.
+# @!method error
+#   An object constructed from the `_error` field of the result's value.
+# @!method ok
+#   Whether the result was successful.
+# @!method status
+#   Either `success` if the result was successful or `failure`.
+# @!method stdout
+#   The value of 'stdout' output by the container.
+# @!method stderr
+#   The value of 'stderr' output by the container.
+# @!method to_data
+#   A serialized representation of `ContainerResult`.
+#
+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/datatypes/resourceinstance.rb

@@ -1,5 +1,48 @@
 # frozen_string_literal: true
 
+# `ResourceInstance` objects are used to store the observed and desired state of a
+# target's resource and to track events for the resource. These objects do not
+# modify or interact with a target's resources.
+#
+# > The `ResourceInstance` data type is experimental and might change in a future
+# > release. You can learn more about this data type and how to use it in the
+# > [experimental features
+# > documentation](experimental_features.md#resourceinstance-data-type).
+#
+# @param events
+#   Events for the resource.
+# @param desired_state
+#   [Attributes](https://puppet.com/docs/puppet/latest/lang_resources.html#attributes) describing
+#   the desired state of the resource.
+# @param state
+#   [Attributes](https://puppet.com/docs/puppet/latest/lang_resources.html#attributes) describing
+#   the observed state of the resource.
+# @param target
+#   The resource's target.
+# @param title
+#   The [resource title](https://puppet.com/docs/puppet/latest/lang_resources.html#title).
+# @param type
+#   The [resource type](https://puppet.com/docs/puppet/latest/lang_resources.html#resource-types).
+#
+# @!method []
+#   Accesses the `state` hash directly and returns the value for the specified
+#   attribute. This function does not use dot noation. Call the function directly
+#   on the `ResourceInstance`. For example, `$resource['ensure']`.
+# @!method add_event(event)
+#   Add an event for the resource.
+# @!method overwrite_desired_state(desired_state)
+#   Overwrites the desired state of the resource.
+# @!method overwrite_state(state)
+#   Overwrites the observed state of the resource.
+# @!method set_desired_state(desired_state)
+#   Sets attributes describing the desired state of the resource. Performs a shallow
+#   merge with existing desired state.
+# @!method set_state(state)
+#   Sets attributes describing the observed state of the resource. Performs a shallow
+#   merge with existing state.
+# @!method reference
+#   The resources reference string. For example, `File[/etc/puppetlabs]`.
+#
 Puppet::DataTypes.create_type('ResourceInstance') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/result.rb

@@ -1,5 +1,34 @@
 # frozen_string_literal: true
 
+# For each target that you execute an action on, Bolt returns a `Result` object
+# and adds the `Result` to a `ResultSet` object. A `Result` object contains
+# information about the action you executed on the target.
+#
+# @param target
+#   The target the result is from.
+# @param value
+#   The output or return of executing on the target.
+#
+# @!method []
+#   Accesses the `value` hash directly and returns the value for the key. This
+#   function does not use dot nation. Call the function directly on the `Result`.
+#   For example, `$result['key']`.
+# @!method action
+#   The type of result. For example, `task` or `command`.
+# @!method error
+#   An object constructed from the `_error` field of the result's `value`.
+# @!method message
+#   The `_output` field of the result's value.
+# @!method ok
+#   Whether the result was successful.
+# @!method sensitive
+#   The `_sensitive` field of the result's value, wrapped in a `Sensitive` object.
+#   Call `unwrap()` to extract the value.
+# @!method status
+#   Either `success` if the result was successful or `failure`.
+# @!method to_data
+#   A serialized representation of `Result`.
+#
 Puppet::DataTypes.create_type('Result') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/resultset.rb

@@ -1,5 +1,39 @@
 # frozen_string_literal: true
 
+# For each target that you execute an action on, Bolt returns a `Result` object
+# and adds the `Result` to a `ResultSet` object. In the case of [apply
+# actions](applying_manifest_blocks.md), Bolt returns a `ResultSet` with one or
+# more `ApplyResult` objects.
+#
+# @param results
+#   All results in the set.
+#
+# @!method []
+#   The accessed results. This function does not use dot notation. Call the
+#   function directly on the `ResultSet`. For example, `$results[0]`.
+# @!method count
+#   The number of results in the set.
+# @!method empty
+#   Whether the set is empty.
+# @!method error_set
+#   The set of failing results.
+# @!method filter_set
+#   Filters a set of results by the contents of the block.
+# @!method find(target_name)
+#   Retrieves a result for a specified target.
+# @!method first
+#   The first result in the set. Useful for unwrapping single results.
+# @!method names
+#   The names of all targets that have a `Result` in the set.
+# @!method ok
+#   Whether all results were successful. Equivalent to `$results.error_set.empty`.
+# @!method ok_set
+#   The set of successful results.
+# @!method targets
+#   The list of targets that have results in the set.
+# @!method to_data
+#   An array of serialized representations of each result in the set.
+#
 Puppet::DataTypes.create_type('ResultSet') do
   interface <<-PUPPET
     attributes => {

data/bolt-modules/boltlib/lib/puppet/datatypes/target.rb

@@ -1,5 +1,60 @@
 # frozen_string_literal: true
 
+# The `Target` object represents a target and its specific connection options.
+#
+# @param config
+#   The inventory configuration for the target. This function returns the
+#   configuration set directly on the target in `inventory.yaml` or set in
+#   a plan using `Target.new` or `set_config()`. It does not return default
+#   configuration values or configuration set in Bolt configuration files.
+# @param facts
+#   The target's facts. This function does not look up facts for a target and
+#   only returns the facts specified in an `inventory.yaml` file or set on a
+#   target during a plan run. To retrieve facts for a target and set them in
+#   inventory, run the [facts](writing_plans.md#collect-facts-from-targets)
+#   plan or [puppetdb_fact](writing_plans.md#collect-facts-from-puppetdb)
+#   plan.
+# @param features
+#   The target's features.
+# @param name
+#   The target's human-readable name, or its URI if a name was not given.
+# @param plugin_hooks
+#   The target's `plugin_hooks` [configuration
+#   options](bolt_inventory_reference.md#plugin-hooks-1).
+# @param resources
+#   The target's resources. This function does not look up resources for a
+#   target and only returns resources set on a target during a plan run.
+# @param safe_name
+#   The target's safe name. Equivalent to `name` if a name was given, or the
+#   target's `uri` with any password omitted.
+# @param target_alias
+#   The target's aliases.
+# @param uri
+#   The target's URI.
+# @param vars
+#   The target's variables.
+#
+# @!method host
+#   The target's hostname.
+# @!method password
+#   The password to use when connecting to the target.
+# @!method port
+#   The target's connection port.
+# @!method protocol
+#   The protocol used to connect to the target. This is equivalent to the target's
+#   `transport`, expect for targets using the `remote` transport. For example,
+#   a target with the URI `http://example.com` using the `remote` transport would
+#   return `http` for the `protocol`.
+# @!method transport
+#   The transport used to connect to the target.
+# @!method transport_config
+#   The merged configuration for the target's `transport`. This function returns
+#   configuration that includes defaults set by Bolt, configuration set in
+#   `inventory.yaml`, configuration set in `bolt-defaults.yaml`, and configuration
+#   set in a plan using `set_config()`.
+# @!method user
+#   The user to connect to the target.
+#
 Puppet::DataTypes.create_type('Target') do
   begin
     inventory = Puppet.lookup(:bolt_inventory)

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

@@ -8,6 +8,7 @@ require 'bolt/error'
 Puppet::Functions.create_function(:add_to_group) do
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param group The name of the group to add targets to.
+  # @return [Array[Target]] The targets.
   # @example Add new Target to group.
   #   Target.new('foo@example.com', 'password' => 'secret').add_to_group('group1')
   # @example Add new target to group by name.

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

@@ -16,6 +16,7 @@ Puppet::Functions.create_function(:apply_prep) do
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param options Options hash.
   # @option options [Array] _required_modules An array of modules to sync to the target.
+  # @return [nil]
   # @example Prepare targets by name.
   #   apply_prep('target1,target2')
   dispatch :apply_prep do

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

@@ -10,6 +10,7 @@ Puppet::Functions.create_function(:parallelize, Puppet::Functions::InternalFunct
   # Map a block onto an array, where each array element executes in parallel.
   # This function is experimental.
   # @param data The array to apply the block to.
+  # @param block The code block to execute for each array element.
   # @return [Array] An array of PlanResult objects. Each input from the input
   #   array returns a corresponding PlanResult object.
   # @example Execute two tasks on two targets.

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

@@ -11,6 +11,7 @@ require 'bolt/error'
 Puppet::Functions.create_function(:remove_from_group) do
   # @param target A pattern identifying a single target.
   # @param group The name of the group to remove the target from.
+  # @return [nil]
   # @example Remove Target from group.
   #   remove_from_group('foo@example.com', 'group1')
   # @example Remove failing Targets from the rest of a plan

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