bolt 3.6.0 → 3.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa3e5ea7d868b032557568e9635fcf159f00b81e4961dce4032246cc150a7c16
-  data.tar.gz: 0e9fada8a0518ab174412e21ec843091272cb0afe87980703ebd6d8ed91002dd
+  metadata.gz: f04dc4247f20f08ee8cfe33500b7ba9477963290ab5303b5f2c72ba60c529e1d
+  data.tar.gz: 4ebdf00f011c6d3de0e1b8e47f0763bfab04857fe4611391cf9bc800597c140e
 SHA512:
-  metadata.gz: 66d8df12e0142b6d5872a40f7c0d97b0438c833e4681be6646e17b85496c3a9e1148ff0a2ff34572e0ce788861d928c406dddcb97feb5281ac0d7eb2d7d14ead
-  data.tar.gz: f6dafaa37a4af7633610e26cc084d69c865f0b8df18221d407f2ee077e58e0a582e88cccf49d3a590e7984d56d8ac467ee8704e6ac0e60cc7e37b1a846396d26
+  metadata.gz: 5615936c79c5f157142e1703a83c9cf28e6ef2b91c090826130f57ac9dc636888847ddd87f01374053c768cf9d4e87a929f654126f6b37375ea1ae1cdc670530
+  data.tar.gz: 270c4669aff29a221c9a7711b7bac715bf6e821a01318f45866fdbadbf77e2e93424722db13b10812dc777d4dbc78c116be992f3a908365bc392820cbb6eeb0b

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,8 @@ 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.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @return [nil]
   # @example Prepare targets by name.
   #   apply_prep('target1,target2')
   dispatch :apply_prep do
@@ -70,7 +72,8 @@ Puppet::Functions.create_function(:apply_prep) do
         .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'apply_prep')
     end
 
-    options = options.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    # Unfreeze this
+    options = options.slice(*%w[_run_as _required_modules])
 
     applicator = Puppet.lookup(:apply_executor)
 
@@ -78,14 +81,14 @@ Puppet::Functions.create_function(:apply_prep) do
 
     targets = inventory.get_targets(target_spec)
 
-    required_modules = options[:required_modules].nil? ? nil : Array(options[:required_modules])
-    if required_modules&.any?
+    required_modules = options.delete('_required_modules').to_a
+    if required_modules.any?
       Puppet.debug("Syncing only required modules: #{required_modules.join(',')}.")
     end
 
     # Gather facts, including custom facts
     plugins = applicator.build_plugin_tarball do |mod|
-      next unless required_modules.nil? || required_modules.include?(mod.name)
+      next unless required_modules.empty? || required_modules.include?(mod.name)
       search_dirs = []
       search_dirs << mod.plugins if mod.plugins?
       search_dirs << mod.pluginfacts if mod.pluginfacts?
@@ -106,8 +109,9 @@ Puppet::Functions.create_function(:apply_prep) do
             opts = t.plugin_hooks&.fetch('puppet_library').dup
             plugin_name = opts.delete('plugin')
             hook = inventory.plugins.get_hook(plugin_name, :puppet_library)
+            # Give plan function options precedence over inventory options
             { 'target' => t,
-              'hook_proc' => hook.call(opts, t, self) }
+              'hook_proc' => hook.call(opts.merge(options), t, self) }
           rescue StandardError => e
             Bolt::Result.from_exception(t, e)
           end
@@ -131,7 +135,7 @@ Puppet::Functions.create_function(:apply_prep) do
 
         task = applicator.custom_facts_task
         arguments = { 'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins) }
-        results = executor.run_task(targets, task, arguments)
+        results = run_task(targets, task, arguments, options)
 
         # TODO: Standardize RunFailure type with error above
         raise Bolt::RunFailure.new(results, 'run_task', task.name) unless results.ok?

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