bolt 2.6.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca1602020625348ee5ba03e246feeb9263ca10fdcda10e13bba36eb674dcdfba
-  data.tar.gz: bdde3554a2406f427f57d02f2e0063e592b7ceba235656c406e9f1ece3899c75
+  metadata.gz: ffe8fa93c2b9de411d9c2ef46c6c68deae3e10c7b711451dd1acf12034952b31
+  data.tar.gz: 4892ece130a2c4c8d70aa6315df85c13be920c290c2e337dddf2b493180bea58
 SHA512:
-  metadata.gz: 13bcc53364488a1f37ebc19821c6429bcbcc055a543f9b581352b03c403793579290af88be0b92416506c3ddd9f23e775c7d9b9a6d2369aed3c38b0ef162da8f
-  data.tar.gz: ea09c6b92cc08d1cd893c136775070df2f6d79097663c58a96212bfdcf23984fe39fd5690d706f4802a61cd384bfe8139e446914506938605ba6d4771f272d63
+  metadata.gz: b95e67238b0af8b5ded1c2f14f1514fb5ab715ae43afbca3247c4f4224d7f403385e0b3f6072babbc90faeb8bcaa4d7cc0b79319258f509340fe765c3e9e13b7
+  data.tar.gz: 9e1584102d3b103632e36d9c922df007c9b780d69a088b964ef59ff4162e94abdc12693e61fea42c5256a97ebf245e2dd4222d4019d98db2d658a10b4f15e317

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

@@ -117,7 +117,7 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
         # undef/nil
         result = catch(:return) do
           scope.with_global_scope do |global_scope|
-            closure.call_by_name_with_scope(global_scope, params, true)
+            executor.run_plan(global_scope, closure, params)
           end
           nil
         end&.value

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]]