bolt 2.8.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdb245ba4347b6309414b645bea7e8829651886d3f85152217801ce7463fdfb6
-  data.tar.gz: 4e93d16cbb9d5cd0314f1c12031cd1e7d1ca9eb0c40186119f15a902aa0732d9
+  metadata.gz: c36dc3edc9637ac83eab0734e6143961ff7c97f4cbc0866ce8e1b5a0b5d318c2
+  data.tar.gz: c52ea03e1354361836c6d76c108735e2f8525aa5e8132f87cf895b5a0f2d802d
 SHA512:
-  metadata.gz: 5264e15f6e29f8d2e8cd9b02f67161e110215c20161c9e5ef22cf85294597eb262c40f0e13491dcb83c683b5c11930bc26fa1f8e5b80bee5ce485c60567fa8f5
-  data.tar.gz: 3b6053135ba279dc70b41cfa13dcd7c5b00a70fa8dd2ed3370bcdd8b1e9c33b33ec2ea817bc6fc5c7afb6114a5abe1c93ea328e432c5b1748c22af04daad5a6f
+  metadata.gz: ded5edab2a28a3a50d2eb9c9d2a1ccad43eae0272b09a609b219a78516bd32f8bff0e35751a95629d4d918cf3a22883d47a90c5c0f402c5aeedaffaab5dfc546
+  data.tar.gz: acde1204c706c49926a33b074da9b5262d1e6d11d27137bec55d7ea80a3ec7e009a1defc309e1f9a7fe824db9c0d4ce92963ddc6d3ae3d2619550fc5c4164ed3

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

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

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.

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:

data/lib/bolt/applicator.rb

@@ -34,6 +34,8 @@ module Bolt
           search_dirs << mod.plugins if mod.plugins?
           search_dirs << mod.pluginfacts if mod.pluginfacts?
           search_dirs << mod.files if mod.files?
+          type_files = "#{mod.path}/types"
+          search_dirs << type_files if File.exist?(type_files)
           search_dirs
         end
       end
@@ -181,7 +183,7 @@ module Bolt
                                                                        rich_data: true,
                                                                        symbol_as_string: true,
                                                                        type_by_reference: true,
-                                                                       local_reference: false)
+                                                                       local_reference: true)
 
       scope = {
         code_ast: ast,

data/lib/bolt/apply_result.rb

@@ -57,7 +57,7 @@ module Bolt
           msg = "Report result contains an '_output' key. Catalog application may have printed extraneous output to stdout: #{result['_output']}"
           # rubocop:enable Layout/LineLength
         else
-          msg = "Report did not contain all expected keys missing: #{missing_keys.join(' ,')}"
+          msg = "Report did not contain all expected keys missing: #{missing_keys.join(', ')}"
         end
 
         { 'msg' => msg,