bolt 2.7.0 → 2.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9354d4101556422d8d97c758b64a4e717a9b24488d11cfe48042ebe79e1a28fa
-  data.tar.gz: 3ca45b8616f2ff1aa53c67cccd150d06c7a2d8897a11b3ffdfda352d6d10ec0c
+  metadata.gz: c5e8e35ad928f8c0b182e0ce9457e5a33e0450da886f91b59637521fd72dc624
+  data.tar.gz: d6b4c4844b91c6cfd8122422b37ebe567bb9a2be9557b3ceb3b3b266b599ca79
 SHA512:
-  metadata.gz: 8afb009f9b4d602b3255d86dac20551fae9389782abd2dbb3bb256eb3431a33ad7e8bfa8c87d3ffcb14d9c0aad551a5ddb2df5df80a01d8e41b4ebe49a4a2ff5
-  data.tar.gz: b3b471d539c81f37bfcfe1b2b7a3e4a84db0ada296e4300a56830d5a41ad91db96efb9583b84027f85a69d0588f7c0a2fb977d6da24aa1f08e16aea856fb6d03
+  metadata.gz: 22b535ce7535ed5eb746c51f08794aa399f55be9e3b2e7ce83f1a38650f23902808245fe4162c033d3024a21dd1a1dd452e341eb4de34ebe9b2872b71ea17e59
+  data.tar.gz: dc9ec1c71c2509dcabe92da46b3432d2b2c1e42b313a5dc274afc665bf739dd6b6582634ec5c5367b5dc6835cdbb387840344c20405249e304d8b43681ee9ac0

data/Puppetfile

@@ -6,7 +6,7 @@ moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
 mod 'puppetlabs-service', '1.2.0'
-mod 'puppetlabs-puppet_agent', '3.0.2'
+mod 'puppetlabs-puppet_agent', '3.2.0'
 mod 'puppetlabs-facts', '1.0.0'
 
 # Core types and providers for Puppet 6
@@ -24,7 +24,7 @@ mod 'puppetlabs-zone_core', '1.0.3'
 # Useful additional modules
 mod 'puppetlabs-package', '1.1.0'
 mod 'puppetlabs-puppet_conf', '0.6.0'
-mod 'puppetlabs-python_task_helper', '0.4.0'
+mod 'puppetlabs-python_task_helper', '0.4.3'
 mod 'puppetlabs-reboot', '3.0.0'
 mod 'puppetlabs-ruby_task_helper', '0.5.1'
 mod 'puppetlabs-ruby_plugin_helper', '0.1.0'
@@ -32,7 +32,8 @@ mod 'puppetlabs-ruby_plugin_helper', '0.1.0'
 # Plugin modules
 mod 'puppetlabs-aws_inventory', '0.5.0'
 mod 'puppetlabs-azure_inventory', '0.3.0'
-mod 'puppetlabs-gcloud_inventory', '0.1.0'
+mod 'puppetlabs-gcloud_inventory', '0.1.1'
+mod 'puppetlabs-pkcs7', '0.1.0'
 mod 'puppetlabs-terraform', '0.5.0'
 mod 'puppetlabs-vault', '0.3.0'
 mod 'puppetlabs-yaml', '0.2.0'

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

@@ -17,5 +17,7 @@ Puppet::DataTypes.create_type('ApplyResult') do
 
   load_file('bolt/apply_result')
 
+  # Needed for Puppet to recognize Bolt::ApplyResult as a Puppet object when deserializing
+  Bolt::ApplyResult.include(Puppet::Pops::Types::PuppetObject)
   implementation_class Bolt::ApplyResult
 end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+Puppet::DataTypes.create_type('ResourceInstance') do
+  interface <<-PUPPET
+    attributes => {
+      'target'        => Target,
+      'type'          => Variant[String[1], Type[Resource]],
+      'title'         => String[1],
+      'state'         => Optional[Hash[String[1], Data]],
+      'desired_state' => Optional[Hash[String[1], Data]],
+      'events'        => Optional[Array[Hash[String[1], Data]]]
+    },
+    functions => {
+      add_event               => Callable[[Hash[String[1], Data]], [Hash[String[1], Data]]],
+      set_state               => Callable[[Hash[String[1], Data]], Hash[String[1], Data]],
+      overwrite_state         => Callable[[Hash[String[1], Data]], Hash[String[1], Data]],
+      set_desired_state       => Callable[[Hash[String[1], Data]], Hash[String[1], Data]],
+      overwrite_desired_state => Callable[[Hash[String[1], Data]], Hash[String[1], Data]],
+      reference               => Callable[[], String]
+    }
+  PUPPET
+
+  load_file('bolt/resource_instance')
+  # Needed for Puppet to recognize Bolt::ResourceInstance as a Puppet object when deserializing
+  Bolt::ResourceInstance.include(Puppet::Pops::Types::PuppetObject)
+  implementation_class Bolt::ResourceInstance
+end

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

@@ -19,5 +19,7 @@ Puppet::DataTypes.create_type('Result') do
 
   load_file('bolt/result')
 
+  # Needed for Puppet to recognize Bolt::Result as a Puppet object when deserializing
+  Bolt::Result.include(Puppet::Pops::Types::PuppetObject)
   implementation_class Bolt::Result
 end

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

@@ -25,5 +25,7 @@ Puppet::DataTypes.create_type('ResultSet') do
 
   load_file('bolt/result_set')
 
+  # Needed for Puppet to recognize Bolt::ResultSet as a Puppet object when deserializing
+  Bolt::ResultSet.include(Puppet::Pops::Types::PuppetObject)
   implementation_class Bolt::ResultSet
 end

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

@@ -8,8 +8,6 @@ Puppet::DataTypes.create_type('Target') do
     target_implementation_class = Bolt::Target
   end
 
-  require 'bolt/target'
-
   interface <<-PUPPET
     attributes => {
       uri => { type => Optional[String[1]], kind => given_or_derived },
@@ -20,7 +18,8 @@ Puppet::DataTypes.create_type('Target') do
       vars => { type => Optional[Hash[String[1], Data]], kind => given_or_derived },
       facts => { type => Optional[Hash[String[1], Data]], kind => given_or_derived },
       features => { type => Optional[Array[String[1]]], kind => given_or_derived },
-      plugin_hooks => { type => Optional[Hash[String[1], Data]], kind => given_or_derived }
+      plugin_hooks => { type => Optional[Hash[String[1], Data]], kind => given_or_derived },
+      resources => { type => Optional[Hash[String[1], ResourceInstance]], kind => given_or_derived }
     },
     functions => {
       host => Callable[[], Optional[String]],
@@ -33,5 +32,7 @@ Puppet::DataTypes.create_type('Target') do
     }
   PUPPET
 
+  # Needed for Puppet to recognize targets as Puppet objects when deserializing
+  target_implementation_class.include(Puppet::Pops::Types::PuppetObject)
   implementation_class target_implementation_class
 end

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

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'bolt/pal'
+require 'bolt/task'
+
+# Runs a given instance of a `Task` with target-specific parameters on the given set of targets and
+# returns the result from each. This function differs from {run_task} by accepting a block that returns
+# a `Hash` of target-specific parameters that are passed to the task. This can be used to send parameters
+# based on a target's attributes, such as its `facts`, or to use conditional logic to determine the
+# parameters a task should receive for a specific target.
+#
+# This function does nothing if the list of targets is empty.
+#
+# > **Note:** Not available in apply block
+#
+# > **Note:** Not available to targets using the pcp transport
+Puppet::Functions.create_function(:run_task_with) do
+  # Run a task with target-specific parameters.
+  # @param task_name The task to run.
+  # @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 [Boolean] _noop Run the task in noop mode if available.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @param block A block that returns a `Hash` of target-specific parameters for the task.
+  # @return A list of results, one entry per target.
+  # @example Run a task with target-specific parameters as root
+  #   run_task_with('my_task', $targets, '_run_as' => 'root') |$t| {
+  #     { 'param1' => $t.vars['var1'],
+  #       'param2' => $t.vars['var2'] }
+  #   }
+  dispatch :run_task_with do
+    param 'String[1]', :task_name
+    param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String[1], Any]', :options
+    required_block_param 'Callable[Target]', :block
+    return_type 'ResultSet'
+  end
+
+  # Run a task with target-specific parameters, logging the provided description.
+  # @param task_name The task to run.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [Boolean] _noop Run the task in noop mode if available.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @param block A block that returns a `Hash` of target-specific parameters for the task.
+  # @return A list of results, one entry per target.
+  # @example Run a task with target-specific parameters and a description
+  #   run_task_with('my_task', $targets, 'Update system packages') |$t| {
+  #     { 'param1' => $t.vars['var1'],
+  #       'param2' => $t.vars['var2'] }
+  #   }
+  dispatch :run_task_with_with_description do
+    param 'String[1]', :task_name
+    param 'Boltlib::TargetSpec', :targets
+    param 'Optional[String]', :description
+    optional_param 'Hash[String[1], Any]', :options
+    required_block_param 'Callable[Target]', :block
+    return_type 'ResultSet'
+  end
+
+  def run_task_with(task_name, targets, options = {}, &block)
+    run_task_with_with_description(task_name, targets, nil, options, &block)
+  end
+
+  def run_task_with_with_description(task_name, targets, description, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(
+          Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+          action: 'run_task_with'
+        )
+    end
+
+    executor  = Puppet.lookup(:bolt_executor)
+    inventory = Puppet.lookup(:bolt_inventory)
+    error_set = []
+
+    # Report to analytics
+    executor.report_function_call(self.class.name)
+    executor.report_bundled_content('Task', task_name)
+
+    # Keep valid metaparameters, discarding everything else
+    options = options.select { |k, _v| k.start_with?('_') }
+                     .transform_keys { |k| k.sub(/^_/, '').to_sym }
+
+    options[:description] = description if description
+
+    # Get all the targets
+    targets = Array(inventory.get_targets(targets))
+
+    # If all targets use the 'pcp' transport, use a fake task instead of loading the local definition
+    # Otherwise, load the local task definition
+    if (pcp_only = targets.any? && targets.all? { |t| t.transport == 'pcp' })
+      task = Bolt::Task.new(task_name, {}, [{ 'name' => '', 'path' => '' }])
+    else
+      task_signature = Puppet::Pal::ScriptCompiler.new(closure_scope.compiler).task_signature(task_name)
+
+      if task_signature.nil?
+        raise Bolt::Error.unknown_task(task_name)
+      end
+
+      task = Bolt::Task.from_task_signature(task_signature)
+    end
+
+    # Map the targets to their specific parameters and merge with the defaults
+    target_mapping = targets.each_with_object({}) do |target, mapping|
+      params = yield(target)
+
+      # Parameters returned from the block should be a Hash. If they're not, create a failing
+      # Result for the target that will later be added to the ResultSet.
+      unless params.is_a?(Hash)
+        exception = with_stack(
+          :TYPE_MISMATCH,
+          "Block must return a Hash of parameters, received #{params.class}"
+        )
+        error_set << Bolt::Result.from_exception(target, exception, action: 'task')
+        next
+      end
+
+      # If parameters are mismatched, create a failing result for the target that will later
+      # be added to the ResultSet.
+      unless pcp_only
+        params = task.parameter_defaults.merge(params)
+
+        type_match = task_signature.runnable_with?(params) do |mismatch_message|
+          exception = with_stack(:TYPE_MISMATCH, mismatch_message)
+          error_set << Bolt::Result.from_exception(target, exception, action: 'task')
+        end
+
+        next unless type_match
+      end
+
+      # If there is a type mismatch between the type Data and the type of the params, create
+      # a failing result for the target that will later be added to the ResultSet.
+      unless Puppet::Pops::Types::TypeFactory.data.instance?(params)
+        params_t = Puppet::Pops::Types::TypeCalculator.infer_set(params)
+        desc = Puppet::Pops::Types::TypeMismatchDescriber.singleton.describe_mismatch(
+          'Task parameters are not of type Data. run_task_with()',
+          Puppet::Pops::Types::TypeFactory.data, params_t
+        )
+        exception = with_stack(:TYPE_NOT_DATA, desc)
+        error_set << Bolt::Result.from_exception(target, exception, action: 'task')
+        next
+      end
+
+      # Wrap parameters marked with '"sensitive": true' in the task metadata with a
+      # Sensitive wrapper type. This way it's not shown in logs.
+      if (param_spec = task.parameters)
+        params.each do |k, v|
+          if param_spec[k] && param_spec[k]['sensitive']
+            params[k] = Puppet::Pops::Types::PSensitiveType::Sensitive.new(v)
+          end
+        end
+      end
+
+      mapping[target] = task.parameter_defaults.merge(params)
+    end
+
+    # Add a noop parameter if the function was called with the noop metaparameter.
+    if options[:noop]
+      if task.supports_noop
+        target_mapping.each_value { |params| params['_noop'] = true }
+      else
+        raise with_stack(:TASK_NO_NOOP, 'Task does not support noop')
+      end
+    end
+
+    if targets.empty?
+      Bolt::ResultSet.new([])
+    else
+      # Combine the results from the task run with any failing results that were
+      # generated earlier when creating the target mapping
+      task_result = executor.run_task_with(target_mapping, task, options)
+      result = Bolt::ResultSet.new(task_result.results + error_set)
+
+      if !result.ok && !options[:catch_errors]
+        raise Bolt::RunFailure.new(result, 'run_task', task_name)
+      end
+
+      result
+    end
+  end
+
+  def with_stack(kind, msg)
+    issue = Puppet::Pops::Issues.issue(kind) { msg }
+    Puppet::ParseErrorWithIssue.from_issue_and_stack(issue)
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Sets one or more ResourceInstances on a Target. This function does not apply or modify
+# resources on a target.
+#
+# For more information about resources see [the
+# documentation](https://puppet.com/docs/puppet/latest/lang_resources.html).
+#
+# > **Note:** The `ResourceInstance` data type is under active development and is subject to
+#   change. You can read more about the data type in the [experimental features
+#   documentation](experimental_features.md#resourceinstance-data-type).
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:set_resources) do
+  # Set multiple resources
+  # @param target The `Target` object to add resources to. See {get_targets}.
+  # @param resources The resources to set on the target.
+  # @return The added `ResourceInstance` objects.
+  # @example Add multiple resources to a target with an array of `ResourceInstance` objects.
+  #   $resource1 = ResourceInstance.new(
+  #     'target' => $target,
+  #     'type'   => 'file',
+  #     'title'  => '/etc/puppetlabs',
+  #     'state'  => { 'ensure' => 'present' }
+  #   )
+  #   $resource2 = ResourceInstance.new(
+  #     'target' => $target,
+  #     'type'   => 'package',
+  #     'title'  => 'openssl',
+  #     'state'  => { 'ensure' => 'installed' }
+  #   )
+  #   $target.set_resources([$resource1, $resource2])
+  # @example Add resources retrieved with [`get_resources`](#get_resources) to a target.
+  #   $target.apply_prep
+  #   $resources = $target.get_resources(Package).first['resources']
+  #   $target.set_resources($resources)
+  dispatch :set_resources do
+    param 'Target', :target
+    param 'Array[Variant[Hash, ResourceInstance]]', :resources
+    return_type 'Array[ResourceInstance]'
+  end
+
+  # Set a single resource
+  # @param target The `Target` object to add resources to. See {get_targets}.
+  # @param resource The resource to set on the target.
+  # @return The added `ResourceInstance` object.
+  # @example Add a single resource to a target with a resource data hash.
+  #   $resource = {
+  #     'type'  => 'file',
+  #     'title' => '/etc/puppetlabs',
+  #     'state' => { 'ensure' => 'present' }
+  #   }
+  #   $target.set_resources($resource)
+  dispatch :set_resource do
+    param 'Target', :target
+    param 'Variant[Hash, ResourceInstance]', :resource
+    return_type 'Array[ResourceInstance]'
+  end
+
+  def set_resources(target, resources)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(
+          Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+          action: 'set_resources'
+        )
+    end
+
+    inventory = Puppet.lookup(:bolt_inventory)
+    executor  = Puppet.lookup(:bolt_executor)
+    executor.report_function_call(self.class.name)
+
+    inventory_target = inventory.get_target(target)
+
+    resources.uniq.map do |resource|
+      if resource.is_a?(Hash)
+        # ResourceInstance expects a Target object, so either get a specified target from
+        # the inventory or use the target this function was called on.
+        resource_target = if resource.key?('target')
+                            inventory.get_target(resource['target'])
+                          else
+                            inventory_target
+                          end
+
+        # Observed state from get_resources() is under the 'parameters' key
+        resource_state = resource['state'] || resource['parameters']
+
+        init_hash = {
+          'target'        => resource_target,
+          'type'          => resource['type'],
+          'title'         => resource['title'],
+          'state'         => resource_state,
+          'desired_state' => resource['desired_state'],
+          'events'        => resource['events']
+        }
+
+        # Calling Bolt::ResourceInstance.new or Bolt::ResourceInstance.from_asserted_hash
+        # will not perform any validation on the parameters. Instead, we need to use the
+        # Puppet constructor to initialize the object, which will first validate the parameters
+        # and then call Bolt::ResourceInstance.from_asserted_hash internally. To do this we
+        # first need to get the Puppet datatype and then call the new function on that type.
+        type = Puppet::Pops::Types::TypeParser.singleton.parse('ResourceInstance')
+        resource = call_function('new', type, init_hash)
+      end
+
+      unless resource.target == inventory_target
+        file, line = Puppet::Pops::PuppetStack.top_of_stack
+        raise Bolt::ValidationError, "Cannot set resource #{resource.reference} for target "\
+                                     "#{resource.target} on target #{inventory_target}. "\
+                                     "#{Puppet::Util::Errors.error_location(file, line)}"
+      end
+
+      inventory_target.set_resource(resource)
+    end
+  end
+
+  def set_resource(target, resource)
+    set_resources(target, [resource])
+  end
+end

data/bolt-modules/boltlib/types/planresult.pp

@@ -2,4 +2,15 @@
 # should be used as the return type of functions that run plans and return the
 # results.
 
-type Boltlib::PlanResult = Variant[Boolean, Numeric, String, Undef, Error, Result, ResultSet, Target, Array[Boltlib::PlanResult], Hash[String, Boltlib::PlanResult]]
+type Boltlib::PlanResult = Variant[Boolean, 
+                                   Numeric,
+                                   String,
+                                   Undef,
+                                   Error,
+                                   Result,
+                                   ApplyResult,
+                                   ResultSet,
+                                   Target,
+                                   ResourceInstance,
+                                   Array[Boltlib::PlanResult],
+                                   Hash[String, Boltlib::PlanResult]]