bolt 2.11.0 → 2.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffe8fa93c2b9de411d9c2ef46c6c68deae3e10c7b711451dd1acf12034952b31
-  data.tar.gz: 4892ece130a2c4c8d70aa6315df85c13be920c290c2e337dddf2b493180bea58
+  metadata.gz: 696f0fbeea26bd6bccad0ab2935e8174b871148bcae962438996e0822a216a7f
+  data.tar.gz: fc865179b5b437a6474e45d1c94139b892cec331fb85511c81ef19b41af4a806
 SHA512:
-  metadata.gz: b95e67238b0af8b5ded1c2f14f1514fb5ab715ae43afbca3247c4f4224d7f403385e0b3f6072babbc90faeb8bcaa4d7cc0b79319258f509340fe765c3e9e13b7
-  data.tar.gz: 9e1584102d3b103632e36d9c922df007c9b780d69a088b964ef59ff4162e94abdc12693e61fea42c5256a97ebf245e2dd4222d4019d98db2d658a10b4f15e317
+  metadata.gz: e0bf903cf991732261e779a665de009b9e45a08c911cab88df738201ebdc8a75b5d4e82cc7585956215b0e93f30b21142a37401f94d5ce8e0d7e41c8014bf499
+  data.tar.gz: ea88a182be0b972869342ef16423089338b13f9e0f540b13da4b133c231f80597646c4f920d254184e5c5b276c08ec6ec6eff0c79aeb456dfd777e68ba4433fc

data/Puppetfile

@@ -33,7 +33,7 @@ mod 'puppetlabs-ruby_plugin_helper', '0.1.0'
 mod 'puppetlabs-aws_inventory', '0.5.0'
 mod 'puppetlabs-azure_inventory', '0.3.0'
 mod 'puppetlabs-gcloud_inventory', '0.1.1'
-mod 'puppetlabs-pkcs7', '0.1.0'
+mod 'puppetlabs-pkcs7', '0.1.1'
 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/resourceinstance.rb

@@ -11,12 +11,13 @@ Puppet::DataTypes.create_type('ResourceInstance') do
       'events'        => Optional[Array[Hash[String[1], Data]]]
     },
     functions => {
-      add_event               => Callable[[Hash[String[1], Data]], [Hash[String[1], Data]]],
+      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]
+      reference               => Callable[[], String],
+      '[]'                    => Callable[[String[1]], Data]
     }
   PUPPET
 

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Lookup a resource in the target's data.
+#
+# 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).
+Puppet::Functions.create_function(:resource) do
+  # Lookup a resource in the target's data.
+  # @param target The Target object to add resources to. See {get_targets}.
+  # @param type The type of the resource
+  # @param title The title of the resource
+  # @return The ResourceInstance if found, or Undef
+  # @example Get the openssl package resource
+  #   $target.apply_prep
+  #   $resources = $target.get_resources(Package).first['resources']
+  #   $target.set_resources($resources)
+  #   $openssl = $target.resource('Package', 'openssl')
+  dispatch :resource do
+    param 'Target', :target
+    param 'Type[Resource]', :type
+    param 'String[1]', :title
+    return_type 'Optional[ResourceInstance]'
+  end
+
+  # Lookup a resource in the target's data, referring to resource as a string
+  # @param target The Target object to add resources to. See {get_targets}.
+  # @param type The type of the resource
+  # @param title The title of the resource
+  # @return The ResourceInstance if found, or Undef
+  dispatch :resource_from_string do
+    param 'Target', :target
+    param 'String[1]', :type
+    param 'String[1]', :title
+    return_type 'Optional[ResourceInstance]'
+  end
+
+  def resource(target, type, title)
+    inventory = Puppet.lookup(:bolt_inventory)
+    executor  = Puppet.lookup(:bolt_executor) { nil }
+    executor&.report_function_call(self.class.name)
+
+    inventory.resource(target, type, title)
+  end
+
+  def resource_from_string(target, type, title)
+    resource(target, type, title)
+  end
+end

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,62 @@ 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]
+
+      # Parameters passed to a plan that the plan is not expecting don't have a model,
+      # so keep the parameter as-is.
+      if model.nil?
+        acc[name] = value
+      elsif 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

@@ -14,26 +14,61 @@ require 'bolt/error'
 #
 # > **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(
+  # 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',
+  #     '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])
+  #
+  #   $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.
-  #   $target.apply_prep
   #   $resources = $target.get_resources(Package).first['resources']
   #   $target.set_resources($resources)
   dispatch :set_resources do
@@ -42,21 +77,12 @@ Puppet::Functions.create_function(:set_resources) do
     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]'
+  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)
@@ -68,11 +94,8 @@ Puppet::Functions.create_function(:set_resources) do
         )
     end
 
+    Puppet.lookup(:bolt_executor).report_function_call(self.class.name)
     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)
@@ -81,15 +104,18 @@ Puppet::Functions.create_function(:set_resources) do
         resource_target = if resource.key?('target')
                             inventory.get_target(resource['target'])
                           else
-                            inventory_target
+                            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'],
+          'type'          => resource_type,
           'title'         => resource['title'],
           'state'         => resource_state,
           'desired_state' => resource['desired_state'],
@@ -105,18 +131,14 @@ Puppet::Functions.create_function(:set_resources) do
         resource = call_function('new', type, init_hash)
       end
 
-      unless resource.target == inventory_target
+      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 #{inventory_target}. "\
+                                     "#{resource.target} on target #{target}. "\
                                      "#{Puppet::Util::Errors.error_location(file, line)}"
       end
 
-      inventory_target.set_resource(resource)
+      target.set_resource(resource)
     end
   end
-
-  def set_resource(target, resource)
-    set_resources(target, [resource])
-  end
 end

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

@@ -9,7 +9,7 @@ Puppet::Functions.create_function(:'file::exists', Puppet::Functions::InternalFu
   # @example Check a file on disk
   #   file::exists('/tmp/i_dumped_this_here')
   # @example check a file from the modulepath
-  #   file::exists('example/files/VERSION')
+  #   file::exists('example/VERSION')
   dispatch :exists do
     scope_param
     required_param 'String', :filename

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

@@ -8,7 +8,7 @@ Puppet::Functions.create_function(:'file::read', Puppet::Functions::InternalFunc
   # @example Read a file from disk
   #   file::read('/tmp/i_dumped_this_here')
   # @example Read a file from the modulepath
-  #   file::read('example/files/VERSION')
+  #   file::read('example/VERSION')
   dispatch :read do
     scope_param
     required_param 'String', :filename

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

@@ -9,7 +9,7 @@ Puppet::Functions.create_function(:'file::readable', Puppet::Functions::Internal
   # @example Check a file on disk
   #   file::readable('/tmp/i_dumped_this_here')
   # @example check a file from the modulepath
-  #   file::readable('example/files/VERSION')
+  #   file::readable('example/VERSION')
   dispatch :readable do
     scope_param
     required_param 'String', :filename

data/lib/bolt/analytics.rb

@@ -29,7 +29,7 @@ module Bolt
     def self.build_client
       logger = Logging.logger[self]
       begin
-        config_file = File.expand_path('~/.puppetlabs/bolt/analytics.yaml')
+        config_file = config_path(logger)
         config = load_config(config_file, logger)
       rescue ArgumentError
         config = { 'disabled' => true }
@@ -51,6 +51,25 @@ module Bolt
       NoopClient.new
     end
 
+    def self.config_path(logger)
+      path     = File.expand_path(File.join('~', '.puppetlabs', 'etc', 'bolt', 'analytics.yaml'))
+      old_path = File.expand_path(File.join('~', '.puppetlabs', 'bolt', 'analytics.yaml'))
+
+      if File.exist?(path)
+        if File.exist?(old_path)
+          message = "Detected analytics configuration files at '#{old_path}' and '#{path}'. Loading "\
+                    "analytics configuration from '#{path}'."
+          logger.warn(message)
+        end
+
+        path
+      elsif File.exist?(old_path)
+        old_path
+      else
+        path
+      end
+    end
+
     def self.load_config(filename, logger)
       if File.exist?(filename)
         YAML.load_file(filename)
@@ -59,7 +78,7 @@ module Bolt
           logger.warn <<~ANALYTICS
             Bolt collects data about how you use it. You can opt out of providing this data.
 
-            To disable analytics data collection, add this line to ~/.puppetlabs/bolt/analytics.yaml :
+            To disable analytics data collection, add this line to ~/.puppetlabs/etc/bolt/analytics.yaml :
               disabled: true
 
             Read more about what data Bolt collects and why here: