bolt 2.15.0 → 2.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 696f0fbeea26bd6bccad0ab2935e8174b871148bcae962438996e0822a216a7f
-  data.tar.gz: fc865179b5b437a6474e45d1c94139b892cec331fb85511c81ef19b41af4a806
+  metadata.gz: a72c179da8e6e3fd3d8f883366e88f98026de00eee08ae2410515b2103a3810d
+  data.tar.gz: 968edc1c0c30a370ed06b1c9bd5498ccaaaa5e15f3c47307cad1e68f2af5dafb
 SHA512:
-  metadata.gz: e0bf903cf991732261e779a665de009b9e45a08c911cab88df738201ebdc8a75b5d4e82cc7585956215b0e93f30b21142a37401f94d5ce8e0d7e41c8014bf499
-  data.tar.gz: ea88a182be0b972869342ef16423089338b13f9e0f540b13da4b133c231f80597646c4f920d254184e5c5b276c08ec6ec6eff0c79aeb456dfd777e68ba4433fc
+  metadata.gz: a906282180c5df824978979d8e12da5cbe2f835ccef2ae65f2e2fc892bcfa1514a4f8f76418b866fe9cbfe8ce8f8f28b66306055b7acc67de6a7a2e13bb7edbf
+  data.tar.gz: ee4c33740e8e29ad4b3026e5b75b3f0d29556c92e9277bc34101c5f8acfe80db599389c8544aab5946c6c444502a49ddb515da0a854b5796b0aae54fc0875ffc

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

@@ -25,6 +25,7 @@ Puppet::Functions.create_function(:add_facts) do
 
     inventory = Puppet.lookup(:bolt_inventory)
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     inventory.add_facts(target, facts)

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

@@ -29,6 +29,7 @@ Puppet::Functions.create_function(:add_to_group) do
 
     inventory = Puppet.lookup(:bolt_inventory)
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     inventory.add_to_group(inventory.get_targets(targets), group)

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

@@ -13,10 +13,13 @@ require 'bolt/task'
 # > **Note:** Not available in apply block
 Puppet::Functions.create_function(:apply_prep) do
   # @param targets A pattern or array of patterns identifying a set of targets.
+  # @param options Options hash.
+  # @option options [Array] _required_modules An array of modules to sync to the target.
   # @example Prepare targets by name.
   #   apply_prep('target1,target2')
   dispatch :apply_prep do
     param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String, Data]', :options
   end
 
   def script_compiler
@@ -60,18 +63,34 @@ Puppet::Functions.create_function(:apply_prep) do
     @executor ||= Puppet.lookup(:bolt_executor)
   end
 
-  def apply_prep(target_spec)
+  def apply_prep(target_spec, options = {})
     unless Puppet[:tasks]
       raise Puppet::ParseErrorWithIssue
         .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'apply_prep')
     end
 
+    options = options.transform_keys { |k| k.sub(/^_/, '').to_sym }
+
     applicator = Puppet.lookup(:apply_executor)
 
     executor.report_function_call(self.class.name)
 
     targets = inventory.get_targets(target_spec)
 
+    required_modules = options[:required_modules].nil? ? nil : Array(options[:required_modules])
+    if required_modules&.any?
+      Puppet.debug("Syncing only required modules: #{required_modules.join(',')}.")
+    end
+
+    # Gather facts, including custom facts
+    plugins = applicator.build_plugin_tarball do |mod|
+      next unless required_modules.nil? || required_modules.include?(mod.name)
+      search_dirs = []
+      search_dirs << mod.plugins if mod.plugins?
+      search_dirs << mod.pluginfacts if mod.pluginfacts?
+      search_dirs
+    end
+
     executor.log_action('install puppet and gather facts', targets) do
       executor.without_default_logging do
         # Skip targets that include the puppet-agent feature, as we know an agent will be available.
@@ -109,14 +128,6 @@ Puppet::Functions.create_function(:apply_prep) do
           need_install_targets.each { |target| set_agent_feature(target) }
         end
 
-        # Gather facts, including custom facts
-        plugins = applicator.build_plugin_tarball do |mod|
-          search_dirs = []
-          search_dirs << mod.plugins if mod.plugins?
-          search_dirs << mod.pluginfacts if mod.pluginfacts?
-          search_dirs
-        end
-
         task = applicator.custom_facts_task
         arguments = { 'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins) }
         results = executor.run_task(targets, task, arguments)

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

@@ -37,6 +37,7 @@ Puppet::Functions.create_function(:catch_errors) do
     end
 
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     begin

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'bolt/error'
+
+# Downloads the given file or directory from the given set of targets and saves it to a directory
+# matching the target's name under the given destination directory. Returns the result from each
+# download. This does nothing if the list of targets is empty.
+#
+# > **Note:** Existing content in the destination directory is deleted before downloading from
+# > the targets.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:download_file, Puppet::Functions::InternalFunction) do
+  # Download a file or directory.
+  # @param source The absolute path to the file or directory on the target(s).
+  # @param destination The relative path to the destination directory on the local system. Expands
+  #                    relative to `<project>/downloads/`.
+  # @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 [String] _run_as User to run as using privilege escalation.
+  # @return A list of results, one entry per target, with the path to the downloaded file under the
+  #         `path` key.
+  # @example Download a file from multiple Linux targets to a destination directory
+  #   download_file('/etc/ssh/ssh_config', '~/Downloads', $targets)
+  # @example Download a directory from multiple Linux targets to a project downloads directory
+  #   download_file('/etc/ssh', 'ssh', $targets)
+  # @example Download a file from multiple Linux targets and compare its contents to a local file
+  #   $results = download_file($source, $destination, $targets)
+  #
+  #   $local_content = file::read($source)
+  #
+  #   $mismatched_files = $results.filter |$result| {
+  #     $remote_content = file::read($result['path'])
+  #     $remote_content == $local_content
+  #   }
+  dispatch :download_file do
+    param 'String[1]', :source
+    param 'String[1]', :destination
+    param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  # Download a file or directory, logging the provided description.
+  # @param source The absolute path to the file or directory on the target(s).
+  # @param destination The relative path to the destination directory on the local system. Expands
+  #                    relative to `<project>/downloads/`.
+  # @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 [String] _run_as User to run as using privilege escalation.
+  # @return A list of results, one entry per target, with the path to the downloaded file under the
+  #         `path` key.
+  # @example Download a file from multiple Linux targets to a destination directory
+  #   download_file('/etc/ssh/ssh_config', '~/Downloads', $targets, 'Downloading remote SSH config')
+  dispatch :download_file_with_description do
+    param 'String[1]', :source
+    param 'String[1]', :destination
+    param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  def download_file(source, destination, targets, options = {})
+    download_file_with_description(source, destination, targets, nil, options)
+  end
+
+  def download_file_with_description(source, destination, targets, description = nil, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'download_file')
+    end
+
+    options = options.select { |opt| opt.start_with?('_') }.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    options[:description] = description if description
+
+    executor = Puppet.lookup(:bolt_executor)
+    inventory = Puppet.lookup(:bolt_inventory)
+
+    if (destination = destination.strip).empty?
+      raise Bolt::ValidationError, "Destination cannot be an empty string"
+    end
+
+    if (destination = Pathname.new(destination)).absolute?
+      raise Bolt::ValidationError, "Destination must be a relative path, received absolute path #{destination}"
+    end
+
+    # Prevent path traversal so downloads can't be saved outside of the project downloads directory
+    if (destination.each_filename.to_a & %w[. ..]).any?
+      raise Bolt::ValidationError, "Destination must not include path traversal, received #{destination}"
+    end
+
+    # Paths expand relative to the default downloads directory for the project
+    # e.g. ~/.puppetlabs/bolt/downloads/
+    destination = Puppet.lookup(:bolt_project_data).downloads + destination
+
+    # If the destination directory already exists, delete any existing contents
+    if Dir.exist?(destination)
+      FileUtils.rm_r(Dir.glob(destination + '*'), secure: true)
+    end
+
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    # Ensure that that given targets are all Target instances
+    targets = inventory.get_targets(targets)
+    if targets.empty?
+      call_function('debug', "Simulating file download of '#{source}' - no targets given - no action taken")
+      r = Bolt::ResultSet.new([])
+    else
+      r = executor.download_file(targets, source, destination, options)
+    end
+
+    if !r.ok && !options[:catch_errors]
+      raise Bolt::RunFailure.new(r, 'download_file', source)
+    end
+    r
+  end
+end

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

@@ -17,6 +17,7 @@ Puppet::Functions.create_function(:facts) do
     inventory = Puppet.lookup(:bolt_inventory)
     # Bolt executor not expected when invoked from apply block
     executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
     executor&.report_function_call(self.class.name)
 
     inventory.facts(target)

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

@@ -40,6 +40,7 @@ Puppet::Functions.create_function(:fail_plan) do
     end
 
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     raise Bolt::PlanFailure.new(msg, kind || 'bolt/plan-failure', details, issue_code)

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

@@ -58,6 +58,7 @@ Puppet::Functions.create_function(:get_resources) do
       end
     end
 
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     targets = inventory.get_targets(target_spec)

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

@@ -21,6 +21,7 @@ Puppet::Functions.create_function(:get_target) do
     inventory = Puppet.lookup(:bolt_inventory)
     # Bolt executor not expected when invoked from apply block
     executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
     executor&.report_function_call(self.class.name)
 
     unless inventory.version > 1

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

@@ -27,6 +27,7 @@ Puppet::Functions.create_function(:get_targets) do
     inventory = Puppet.lookup(:bolt_inventory)
     # Bolt executor not expected when invoked from apply block
     executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
     executor&.report_function_call(self.class.name)
 
     inventory.get_targets(names)

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

@@ -20,6 +20,7 @@ Puppet::Functions.create_function(:puppetdb_fact) do
     puppetdb_client = Puppet.lookup(:bolt_pdb_client)
     # Bolt executor not expected when invoked from apply block
     executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
     executor&.report_function_call(self.class.name)
 
     puppetdb_client.facts_for_node(certnames)

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

@@ -22,6 +22,7 @@ Puppet::Functions.create_function(:puppetdb_query) do
     puppetdb_client = Puppet.lookup(:bolt_pdb_client)
     # Bolt executor not expected when invoked from apply block
     executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
     executor&.report_function_call(self.class.name)
 
     puppetdb_client.make_query(query)

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

@@ -31,6 +31,7 @@ Puppet::Functions.create_function(:remove_from_group) do
 
     inventory = Puppet.lookup(:bolt_inventory)
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     inventory.remove_from_group(inventory.get_targets(target), group)

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

@@ -33,6 +33,7 @@ Puppet::Functions.create_function(:resolve_references) do
     end
 
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     plugins = Puppet.lookup(:bolt_inventory).plugins

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

@@ -41,6 +41,7 @@ Puppet::Functions.create_function(:resource) do
   def resource(target, type, title)
     inventory = Puppet.lookup(:bolt_inventory)
     executor  = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
     executor&.report_function_call(self.class.name)
 
     inventory.resource(target, type, title)

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

@@ -13,6 +13,7 @@ Puppet::Functions.create_function(:run_command) do
   # @param options A hash of additional options.
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @option options [String] _run_as User to run as using privilege escalation.
+  # @option options [Hash] _env_vars Map of environment variables to set
   # @return A list of results, one entry per target.
   # @example Run a command on targets
   #   run_command('hostname', $targets, '_catch_errors' => true)
@@ -30,6 +31,7 @@ Puppet::Functions.create_function(:run_command) do
   # @param options A hash of additional options.
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @option options [String] _run_as User to run as using privilege escalation.
+  # @option options [Hash] _env_vars Map of environment variables to set
   # @return A list of results, one entry per target.
   # @example Run a command on targets
   #   run_command('hostname', $targets, 'Get hostname')
@@ -57,6 +59,7 @@ Puppet::Functions.create_function(:run_command) do
     executor = Puppet.lookup(:bolt_executor)
     inventory = Puppet.lookup(:bolt_inventory)
 
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     # Ensure that given targets are all Target instances

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

@@ -64,10 +64,11 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
     # Bolt calls this function internally to trigger plans from the CLI. We
     # don't want to count those invocations.
     unless options[:bolt_api_call]
+      # Send Analytics Report
       executor.report_function_call(self.class.name)
     end
 
-    # Report bundled content, this should capture plans run from both CLI and Plans
+    # Send Analytics Report for bundled content, this should capture plans run from both CLI and Plans
     executor.report_bundled_content('Plan', plan_name)
 
     loaders = closure_scope.compiler.loaders

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

@@ -11,8 +11,9 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
   # @param options A hash of additional options.
   # @option options [Array[String]] arguments An array of arguments to be passed to the script.
-  # @option args [Boolean] _catch_errors Whether to catch raised errors.
-  # @option args [String] _run_as User to run as using privilege escalation.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @option options [Hash] _env_vars Map of environment variables to set
   # @return A list of results, one entry per target.
   # @example Run a local script on Linux targets as 'root'
   #   run_script('/var/tmp/myscript', $targets, '_run_as' => 'root')
@@ -33,8 +34,9 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
   # @param description A description to be output when calling this function.
   # @param options A hash of additional options.
   # @option options [Array[String]] arguments An array of arguments to be passed to the script.
-  # @option args [Boolean] _catch_errors Whether to catch raised errors.
-  # @option args [String] _run_as User to run as using privilege escalation.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @option options [Hash] _env_vars Map of environment variables to set
   # @return A list of results, one entry per target.
   # @example Run a script
   #   run_script('/var/tmp/myscript', $targets, 'Downloading my application')
@@ -64,6 +66,7 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
     executor = Puppet.lookup(:bolt_executor)
     inventory = Puppet.lookup(:bolt_inventory)
 
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     found = Puppet::Parser::Files.find_file(script, scope.compiler.environment)

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

@@ -64,10 +64,11 @@ Puppet::Functions.create_function(:run_task) do
     # Bolt calls this function internally to trigger tasks from the CLI. We
     # don't want to count those invocations.
     unless options[:bolt_api_call]
+      # Send Analytics Report
       executor.report_function_call(self.class.name)
     end
 
-    # Report bundled content, this should capture tasks run from both CLI and Plans
+    # Report Analytics for bundled content, this should capture tasks run from both CLI and Plans
     executor.report_bundled_content('Task', task_name)
 
     # Ensure that given targets are all Target instances

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

@@ -33,6 +33,7 @@ Puppet::Functions.create_function(:set_config) do
 
     inventory = Puppet.lookup(:bolt_inventory)
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     unless inventory.version > 1

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

@@ -33,6 +33,7 @@ Puppet::Functions.create_function(:set_feature) do
 
     inventory = Puppet.lookup(:bolt_inventory)
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     inventory.set_feature(target, feature, value)

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

@@ -94,6 +94,7 @@ Puppet::Functions.create_function(:set_resources) do
         )
     end
 
+    # Send Analytics Report
     Puppet.lookup(:bolt_executor).report_function_call(self.class.name)
     inventory = Puppet.lookup(:bolt_inventory)
 

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

@@ -27,6 +27,7 @@ Puppet::Functions.create_function(:set_var) do
 
     inventory = Puppet.lookup(:bolt_inventory)
     executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     var_hash = { key => value }

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

@@ -67,6 +67,7 @@ Puppet::Functions.create_function(:upload_file, Puppet::Functions::InternalFunct
     executor = Puppet.lookup(:bolt_executor)
     inventory = Puppet.lookup(:bolt_inventory)
 
+    # Send Analytics Report
     executor.report_function_call(self.class.name)
 
     found = Puppet::Parser::Files.find_file(source, scope.compiler.environment)

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

@@ -21,6 +21,7 @@ Puppet::Functions.create_function(:vars) do
     inventory = Puppet.lookup(:bolt_inventory)
     # Bolt executor not expected when invoked from apply block
     executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
     executor&.report_function_call(self.class.name)
 
     inventory.vars(target)