bolt 2.9.0 → 2.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed1409405ce8a0e0367aea1cb1b7e2d194546c594b96932288c9ae81cef73209
-  data.tar.gz: 0cfb52ce0dbeffb427988da5e3e338649d2f65defbeef133f01c745802661ac6
+  metadata.gz: 0fd39267ed3b68619b0e9f40f8415446d0061ebe5367650d50e6e5ab3229d8b9
+  data.tar.gz: b4d88aee228eeccb8c9ed8ebcb6221960c3197f1ac43d4a195e5c3d4a8833a9d
 SHA512:
-  metadata.gz: 986a57cd4c6b101ce69f11dec9b6f95212129c2930aded3d0b0c0d8243bcf98ef66b981af0398ecb79cea291603483057c3df7f82e56fa6ab40f7981f4f7ae0d
-  data.tar.gz: 9ff02c10dd26709f6027c2d9ab45b051d67c0de62c87abe974faee9db28cf2ddde9e086f8cf83e2765bf43e1ff64690d849ad7e032fdc3cbce9990680f5f55f9
+  metadata.gz: 0a225b8e5e695da5268aa9b748c57c06944046ebc4865d76ec8d0f446ec37d0584f2fca2d19ee9910cd5ed5555f8cc15910693a66e813b0b0e6aab48dd9e8789
+  data.tar.gz: 6d2853adea34d7b0006ac0d643f1af8cda862903618fde138cf64079d9b9c433815537c7f70c483fcbb00287462f4762285d5e8e5147b6327c7c5c71346412b4

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'

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,28 @@
+# 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]], Array[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],
+      '[]'                    => Callable[[String[1]], Data]
+    }
+  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/apply_prep.rb

@@ -3,7 +3,7 @@
 require 'bolt/task'
 
 # Installs the `puppet-agent` package on targets if needed, then collects facts,
-# including any custom facts found in Bolt's modulepath. The package is
+# including any custom facts found in Bolt's module path. The package is
 # installed using either the configured plugin or the `task` plugin with the
 # `puppet_agent::install` task.
 #

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

@@ -2,7 +2,7 @@
 
 require 'bolt/task'
 
-# Query the state of resources on a list of targets using resource definitions in Bolt's modulepath.
+# Query the state of resources on a list of targets using resource definitions in Bolt's module path.
 # The results are returned as a list of hashes representing each resource.
 #
 # Requires the Puppet Agent be installed on the target, which can be accomplished with apply_prep

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

@@ -109,6 +109,15 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
       end
     end
 
+    # Wrap Sensitive parameters for plans that are run from the CLI, as it's impossible to pass
+    # a Sensitive value that way. We don't do this for plans run from the run_plan function, as
+    # it can receive Sensitive values as arguments.
+    # This should only happen after expanding target params, otherwise things will blow up if
+    # the targets are wrapped as Sensitive. Hopefully nobody does that, though...
+    if options[:bolt_api_call]
+      params = wrap_sensitive_parameters(params, closure.parameters)
+    end
+
     # wrap plan execution in logging messages
     executor.log_plan(plan_name) do
       result = nil
@@ -169,6 +178,58 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
     end
   end
 
+  # Wrap any Sensitive parameters in the Sensitive wrapper type, unless they are already
+  # wrapped as Sensitive. This will also raise a helpful warning if the type expression
+  # is a complex data type using Sensitive, as we don't handle those cases.
+  def wrap_sensitive_parameters(params, param_models)
+    models = param_models.each_with_object({}) { |param, acc| acc[param.name] = param }
+
+    params.each_with_object({}) do |(name, value), acc|
+      model = models[name]
+
+      if sensitive_type?(model.type_expr)
+        acc[name] = Puppet::Pops::Types::PSensitiveType::Sensitive.new(value)
+      else
+        if model.type_expr.to_s.include?('Sensitive')
+          # Include the location for regular plans. YAML plans don't have this info, so
+          # the location will be suppressed.
+          file = defined?(model.file) ? model.file : :default
+          line = defined?(model.line) ? model.line : :default
+
+          Puppet.warn_once(
+            'unsupported_sensitive_type',
+            name,
+            "Parameter '#{name}' is a complex type using Sensitive, unable to automatically wrap as Sensitive",
+            file,
+            line
+          )
+        end
+
+        acc[name] = value
+      end
+    end
+  end
+
+  # Whether the type is a supported Sensitive type. We only support wrapping parameterized
+  # and non-parameterized Sensitive types (e.g. Sensitive, Sensitive[String])
+  def sensitive_type?(type_expr)
+    # Parameterized Sensitive type (e.g. Sensitive[String])
+    # left_expr is defined whenever the type is parameterized. If this is a parameterized
+    # Sensitive type, then we check the cased_value, which is the stringified version of
+    # the left expression's type.
+    (defined?(type_expr.left_expr) && type_expr.left_expr.cased_value == 'Sensitive') ||
+      # Non-parameterized Sensitive type (Sensitive)
+      # cased_value is defined whenever the type is non-parameterized. If the type expression
+      # defines cased_value, then this is a simple type and we just need to check that it's
+      # Sensitive.
+      (defined?(type_expr.cased_value) && type_expr.cased_value == 'Sensitive') ||
+      # Sensitive type from YAML plans
+      # Type expressions from YAML plans are a different class than those from regular plans.
+      # As long as the type expression is PSensitiveType we can be sure that the type is
+      # either a parameterized or non-parameterized Sensitive type.
+      type_expr.instance_of?(Puppet::Pops::Types::PSensitiveType)
+  end
+
   def targets_to_param(targets, params, param_types)
     nodes_param = param_types.include?('nodes')
     targets_param = param_types['targets']&.any? { |p| p.match?(/TargetSpec/) }

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

@@ -88,8 +88,10 @@ Puppet::Functions.create_function(:run_task) do
 
       task = Bolt::Task.from_task_signature(task_signature)
 
-      # Set the default value for any params that have one and were not provided
-      params = task.parameter_defaults.merge(params)
+      # Set the default value for any params that have one and were not provided or are undef
+      params = task.parameter_defaults.merge(params) do |_, default, passed|
+        passed.nil? ? default : passed
+      end
 
       task_signature.runnable_with?(params) do |mismatch_message|
         raise with_stack(:TYPE_MISMATCH, mismatch_message)

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

@@ -124,7 +124,10 @@ Puppet::Functions.create_function(:run_task_with) do
       # 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)
+        # Set the default value for any params that have one and were not provided or are undef
+        params = task.parameter_defaults.merge(params) do |_, default, passed|
+          passed.nil? ? default : passed
+        end
 
         type_match = task_signature.runnable_with?(params) do |mismatch_message|
           exception = with_stack(:TYPE_MISMATCH, mismatch_message)
@@ -157,7 +160,10 @@ Puppet::Functions.create_function(:run_task_with) do
         end
       end
 
-      mapping[target] = task.parameter_defaults.merge(params)
+      # Set the default value for any params that have one and were not provided or are undef
+      mapping[target] = task.parameter_defaults.merge(params) do |_, default, passed|
+        passed.nil? ? default : passed
+      end
     end
 
     # Add a noop parameter if the function was called with the noop metaparameter.

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

@@ -0,0 +1,144 @@
+# 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 a single resource from a data hash.
+  # @param target The `Target` object to add a resource to. See {get_targets}.
+  # @param resource The resource data hash used to set a resource on the target.
+  # @return An array with the added `ResourceInstance` object.
+  # @example Add a resource to a target from a data hash.
+  #   $resource_hash = {
+  #     'type'  => File,
+  #     'title' => '/etc/puppetlabs',
+  #     'state' => { 'ensure' => 'present' }
+  #   }
+  #
+  #   $target.set_resources($resource_hash)
+  dispatch :set_single_resource_from_hash do
+    param 'Target', :target
+    param 'Hash', :resource
+    return_type 'Array[ResourceInstance]'
+  end
+
+  # Set a single resource from a `ResourceInstance` object
+  # @param target The `Target` object to add a resource to. See {get_targets}.
+  # @param resource The `ResourceInstance` object to set on the target.
+  # @return An array with the added `ResourceInstance` object.
+  # @example Add a resource to a target from a `ResourceInstance` object.
+  #   $resource_instance = ResourceInstance.new(
+  #     'target' => $target,
+  #     'type'   => File,
+  #     'title'  => '/etc/puppetlabs',
+  #     'state'  => { 'ensure' => 'present' }
+  #   )
+  #
+  #   $target.set_resources($resource_instance)
+  dispatch :set_single_resource_from_object do
+    param 'Target', :target
+    param 'ResourceInstance', :resource
+    return_type 'Array[ResourceInstance]'
+  end
+
+  # Set multiple resources from an array of data hashes and `ResourceInstance` objects.
+  # @param target The `Target` object to add resources to. See {get_targets}.
+  # @param resources The resource data hashes and `ResourceInstance` objects to set on the target.
+  # @return An array of the added `ResourceInstance` objects.
+  # @example Add resources from resource data hashes returned from an apply block.
+  #   $apply_results = apply($targets) {
+  #     File { '/etc/puppetlabs':
+  #       ensure => present
+  #     }
+  #     Package { 'openssl':
+  #       ensure => installed
+  #     }
+  #   }
+  #
+  #   $apply_results.each |$result| {
+  #     $result.target.set_resources($result.report['resource_statuses'].values)
+  #   }
+  # @example Add resources retrieved with [`get_resources`](#get_resources) to a target.
+  #   $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
+
+  def set_single_resource_from_hash(target, resource)
+    set_resources(target, [resource])
+  end
+
+  def set_single_resource_from_object(target, resource)
+    set_resources(target, [resource])
+  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
+
+    Puppet.lookup(:bolt_executor).report_function_call(self.class.name)
+    inventory = Puppet.lookup(:bolt_inventory)
+
+    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
+                            target
+                          end
+
+        # Observed state from get_resources() is under the 'parameters' key
+        resource_state = resource['state'] || resource['parameters']
+
+        # Type from apply results is under the 'resource_type' key
+        resource_type = resource['type'] || resource['resource_type']
+
+        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 == target
+        file, line = Puppet::Pops::PuppetStack.top_of_stack
+        raise Bolt::ValidationError, "Cannot set resource #{resource.reference} for target "\
+                                     "#{resource.target} on target #{target}. "\
+                                     "#{Puppet::Util::Errors.error_location(file, line)}"
+      end
+
+      target.set_resource(resource)
+    end
+  end
+end

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

@@ -11,5 +11,6 @@ type Boltlib::PlanResult = Variant[Boolean,
                                    ApplyResult,
                                    ResultSet,
                                    Target,
+                                   ResourceInstance,
                                    Array[Boltlib::PlanResult],
                                    Hash[String, Boltlib::PlanResult]]

data/bolt-modules/file/lib/puppet/functions/file/exists.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-# Check if a file exists.
+# Check if a local file exists using Puppet's
+# `Puppet::Parser::Files.find_file()` function. This will only check files that
+# are on the machine Bolt is run on.
 Puppet::Functions.create_function(:'file::exists', Puppet::Functions::InternalFunction) do
   # @param filename Absolute path or Puppet file path.
   # @return Whether the file exists.

data/bolt-modules/file/lib/puppet/functions/file/join.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Join file paths.
+# Join file paths using ruby's `File.join()` function.
 Puppet::Functions.create_function(:'file::join') do
   # @param paths The paths to join.
   # @return The joined file path.

data/bolt-modules/file/lib/puppet/functions/file/read.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-# Read a file and return its contents.
+# Read a file on localhost and return its contents using ruby's `File.read`. This will
+# only read files on the machine you run Bolt on.
 Puppet::Functions.create_function(:'file::read', Puppet::Functions::InternalFunction) do
   # @param filename Absolute path or Puppet file path.
   # @return The file's contents.

data/bolt-modules/file/lib/puppet/functions/file/readable.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-# Check if a file is readable.
+# Check if a local file is readable using Puppet's
+# `Puppet::Parser::Files.find_file()` function. This will only check files on the
+# machine you run Bolt on.
 Puppet::Functions.create_function(:'file::readable', Puppet::Functions::InternalFunction) do
   # @param filename Absolute path or Puppet file path.
   # @return Whether the file is readable.

data/bolt-modules/file/lib/puppet/functions/file/write.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-# Write a string to a file.
+# Write a string to a file on localhost using ruby's `File.write`. This will
+# only write files to the machine you run Bolt on. Use `write_file()` to write
+# to remote targets.
 Puppet::Functions.create_function(:'file::write') do
   # @param filename Absolute path.
   # @param content File content to write.