bolt 3.6.1 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87e8cf7f5ccf5d0649f608b088e4162495b6f5c1c2887711ab6f4355b6a3934f
-  data.tar.gz: 0bbac1eed6b37508b1e1f1b90f67a7b687f089415e4daf333e63e71d784c3538
+  metadata.gz: 1c6c3fbb5bdf8e8b53493a029b46560616f2ea310092823f863de14ad1fc836b
+  data.tar.gz: f4a3193539da70d75ff36f39a126d6f56710c91e2ff54c465a1477685b6fb19a
 SHA512:
-  metadata.gz: b534fbfc3a4b15ad9b130a24fb3a1274f05592d9dedb185031fe409364e9e0c10b1af5c90571f0e9a9fd0b5d70817d2e5edf17bf25c9750ac801c0e83c872766
-  data.tar.gz: 3032fed7c7493eeb06d97814eee9496c634522905b36ec67e794da36581815a5786d35afb2f413484c3b5b2b578e8107e7b0c224dfb3003095dc47d0d8a643ec
+  metadata.gz: e6c8837f2d6ef2e67ac2be71d150637bcb90af95207812ec22c81557841279a5f148f2348ca6e0d137e42bfd4058009c59439996a208dc6c5c72568a8842e498
+  data.tar.gz: 712b2be84c5ff24749ef1e010d439e05057c48d648394f7d321611d7576a006277d476adb38c6892fa73b380a0288726023643c8b2849a00f9ac164e06fe805f

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# The [`background()` plan function](plan_functions.md#background) returns a
+# `Future` object, which can be passed to the [`wait()` plan
+# function](plan_functions.md#wait) to block on the result of the backgrounded
+# code block.
+#
+# @!method state
+#   Either 'running' if the Future is still executing, 'done' if the Future
+#   finished successfully, or 'error' if the Future finished with an error.
+#
+Puppet::DataTypes.create_type('Future') do
+  interface <<-PUPPET
+    attributes => {},
+    functions => {
+      state => Callable[[], Enum['running', 'done', 'error']],
+    }
+  PUPPET
+
+  load_file('bolt/plan_future')
+
+  # Needed for Puppet to recognize Bolt::Result as a Puppet object when deserializing
+  Bolt::PlanFuture.include(Puppet::Pops::Types::PuppetObject)
+  implementation_class Bolt::PlanFuture
+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,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/background.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Starts a block of code in parallel with the main plan without blocking.
+# Returns a Future object.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:background, Puppet::Functions::InternalFunction) do
+  # Starts a block of code in parallel with the main plan without blocking.
+  # Returns a Future object.
+  # @param name An optional name for legible logs.
+  # @param block The code block to run in the background.
+  # @return A Bolt Future object
+  # @example Start a long-running process
+  #   background() || {
+  #     run_task('superlong::task', $targets)
+  #   }
+  #   run_command("echo 'Continue immediately'", $targets)
+  dispatch :background do
+    scope_param
+    optional_param 'String[1]', :name
+    block_param 'Callable[0, 0]', :block
+    return_type 'Future'
+  end
+
+  def background(scope, name = nil, &block)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'background')
+    end
+
+    executor = Puppet.lookup(:bolt_executor)
+    executor.report_function_call(self.class.name)
+
+    executor.create_future(scope: scope, name: name) do |newscope|
+      # Catch 'return' calls inside the block
+      result = catch(:return) do
+        # Execute the block. Individual plan steps in the block will yield
+        # the Fiber if they haven't finished, so all this needs to do is run
+        # the block.
+        block.closure.call_by_name_with_scope(newscope, {}, true)
+      end
+
+      # If we got a return from the block, get its value
+      # Otherwise the result is the last line from the block
+      result = result.value if result.is_a?(Puppet::Pops::Evaluator::Return)
+
+      # Validate the result is a PlanResult
+      unless Puppet::Pops::Types::TypeParser.singleton.parse('Boltlib::PlanResult').instance?(result)
+        raise Bolt::InvalidParallelResult.new(result.to_s, *Puppet::Pops::PuppetStack.top_of_stack)
+      end
+
+      result
+    rescue Puppet::PreformattedError => e
+      if e.cause.is_a?(Bolt::Error)
+        e.cause
+      else
+        raise e
+      end
+    end
+  end
+end