bolt 3.5.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41eb3934a2ddce5d1021b66f5aca6eccfdb91bdedd5dc08cfdc1cfb4664f91e8
-  data.tar.gz: 8a04142fd9de53e8812cff0c540098a8548a8b18245e300835896b457a86d348
+  metadata.gz: 1f4c856f3322c88dabb51efe39bc7373d96e33f6274785188900e8fbb5488436
+  data.tar.gz: 5e5da3f150093febfc2b6d7e343e9995ea33b044fb4941ed9229944e4735aa72
 SHA512:
-  metadata.gz: 24bc37edf14e9c5d3ef1b8df5d5ed9dd0161ebb44da96e0b2777703c5b71182179ebed740e5d67c04bad41b9ecdb6e0a40d5fcb5ec08eb59171da36a3d5a3756
-  data.tar.gz: 0e5795469709939091282a51df744076e87e40e5dad0f5bc6395d0d7927dcbf5f788bccf23bd5c455c29232faa958ddcbe5130626eb82d056404f8cb1e088cdd
+  metadata.gz: 8f88f29b98a7bab28a4bbae5e860bb4c94fca20dd994241b71f2e5327934a92db1370c77fdb03d5f9a033e626b726e379e3eec510f0316b67b0807aa86920b67
+  data.tar.gz: 8cf9a3bbfde78b7930089a7ada109e03bba5439ea8ef3049d3fa58bc589914881969be783fe667ef5c238613e126c7f79d7dd0db30fcd2f5d9147999086d1df7

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.5.0'
+mod 'puppetlabs-puppet_agent', '4.6.1'
 mod 'puppetlabs-facts', '1.4.0'
 
 # Core types and providers for Puppet 6
@@ -17,7 +17,7 @@ mod 'puppetlabs-sshkeys_core', '2.2.0'
 mod 'puppetlabs-zfs_core', '1.2.0'
 mod 'puppetlabs-cron_core', '1.0.5'
 mod 'puppetlabs-mount_core', '1.0.4'
-mod 'puppetlabs-selinux_core', '1.0.4'
+mod 'puppetlabs-selinux_core', '1.1.0'
 mod 'puppetlabs-yumrepo_core', '1.0.7'
 mod 'puppetlabs-zone_core', '1.0.3'
 
@@ -29,7 +29,7 @@ mod 'puppetlabs-python_task_helper', '0.5.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'
+mod 'puppetlabs-stdlib', '7.0.1'
 
 # Plugin modules
 mod 'puppetlabs-aws_inventory', '0.7.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

@@ -1,5 +1,32 @@
 # 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 => {

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

@@ -108,7 +108,11 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
     # Send Analytics Report
     executor.report_function_call(self.class.name)
 
-    found = Puppet::Parser::Files.find_file(script, scope.compiler.environment)
+    future = executor&.future || {}
+    fallback = future.fetch('file_paths', false)
+
+    # Find the file path if it exists, otherwise return nil
+    found = Bolt::Util.find_file_from_scope(script, scope, fallback)
     unless found && Puppet::FileSystem.exist?(found)
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
         Puppet::Pops::Issues::NO_SUCH_FILE_OR_DIRECTORY, file: script

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

@@ -70,7 +70,11 @@ Puppet::Functions.create_function(:upload_file, Puppet::Functions::InternalFunct
     # Send Analytics Report
     executor.report_function_call(self.class.name)
 
-    found = Puppet::Parser::Files.find_file(source, scope.compiler.environment)
+    future = executor&.future || {}
+    fallback = future.fetch('file_paths', false)
+
+    # Find the file path if it exists, otherwise return nil
+    found = Bolt::Util.find_file_from_scope(source, scope, fallback)
     unless found && Puppet::FileSystem.exist?(found)
       raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
         Puppet::Pops::Issues::NO_SUCH_FILE_OR_DIRECTORY, file: source

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

@@ -9,6 +9,7 @@ Puppet::Functions.create_function(:write_file) do
   # @param content File content to write.
   # @param destination An absolute path on the target(s).
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @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.
   # @return A list of results, one entry per target.

data/bolt-modules/ctrl/lib/puppet/functions/ctrl/do_until.rb

@@ -3,8 +3,10 @@
 # Repeat the block until it returns a truthy value. Returns the value.
 Puppet::Functions.create_function(:'ctrl::do_until') do
   # @param options A hash of additional options.
+  # @param block The code block to repeat.
   # @option options [Numeric] limit The number of times to repeat the block.
   # @option options [Numeric] interval The number of seconds to wait before repeating the block.
+  # @return [nil]
   # @example Run a task until it succeeds
   #   ctrl::do_until() || {
   #     run_task('test', $target, '_catch_errors' => true).ok()