bolt 1.49.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf6891d9f3f208d516d962db7af3e26df0b8de95312c465f3cc8add22948730a
-  data.tar.gz: d58605a7bff94d170ab8c95f3b9a024eb60173f60d5bda83cd29c5084baa7450
+  metadata.gz: 741454338908333d9dfe5a093cd7bc441f5ba64968ca8b24f44c221b6cdd3b18
+  data.tar.gz: 5143668d78e8c4067868cbb2f4c0fc6b9f118472b658b9720325679a70b744e7
 SHA512:
-  metadata.gz: 742d7bd9cf8f7943412e8fbcb363541b787cccfb019e52c913690a00cfe567787fbe16aa20fd5c4a7b0095724f5b5a124c5d4026879c7b3e0f58d342c5c24124
-  data.tar.gz: 436bb36efdefc26efc08de99769af0d9912c1a34caaf0e9255950e4738a92b65ebcf05df20a4add6b47a54add18c1757d11643fb426c214ce840d83dbd80fd86
+  metadata.gz: d2a1789c74010115a7f05ae78bb4a638f1efe9f36ffa5fb7ae13faf4a293bacd51cb00fbde3b42a9356039e0fb5112990fb82883ecae917ef51d36c098b9c1a9
+  data.tar.gz: 07513d68070432a1c48141dfd9f40936d6735edf91d5ebfb954083e459d7a7ba7e2e9a906a338f2452732817893c9cb5ccaac691961810f557055ebabecb2cce

data/Puppetfile

@@ -6,7 +6,7 @@ moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
 mod 'puppetlabs-service', '1.1.0'
-mod 'puppetlabs-puppet_agent', '3.0.1'
+mod 'puppetlabs-puppet_agent', '3.0.2'
 mod 'puppetlabs-facts', '1.0.0'
 
 # Core types and providers for Puppet 6
@@ -30,11 +30,11 @@ mod 'puppetlabs-ruby_task_helper', '0.4.0'
 mod 'puppetlabs-ruby_plugin_helper', '0.1.0'
 
 # Plugin modules
-mod 'puppetlabs-azure_inventory', '0.2.0'
-mod 'puppetlabs-terraform', '0.3.0'
-mod 'puppetlabs-vault', '0.2.2'
-mod 'puppetlabs-aws_inventory', '0.3.0'
-mod 'puppetlabs-yaml', '0.1.0'
+mod 'puppetlabs-azure_inventory', '0.3.0'
+mod 'puppetlabs-terraform', '0.4.0'
+mod 'puppetlabs-vault', '0.3.0'
+mod 'puppetlabs-aws_inventory', '0.4.0'
+mod 'puppetlabs-yaml', '0.2.0'
 
 # If we don't list these modules explicitly, r10k will purge them
 mod 'canary', local: true

data/bolt-modules/boltlib/lib/puppet/datatypes/target.rb

@@ -3,54 +3,33 @@
 Puppet::DataTypes.create_type('Target') do
   begin
     inventory = Puppet.lookup(:bolt_inventory)
-
-    inventory_version = inventory.version
-    if inventory_version != 1
-      target_implementation_class = inventory.target_implementation_class
-    end
+    target_implementation_class = inventory.target_implementation_class
   rescue Puppet::Context::UndefinedBindingError
-    inventory_version = 1
+    target_implementation_class = Bolt::Target
   end
+
   require 'bolt/target'
 
-  if inventory_version == 1
-    interface <<-PUPPET
-      attributes => {
-        uri => String[1],
-        options => { type => Hash[String[1], Data], value => {} }
-      },
-      functions => {
-        name => Callable[[], String[1]],
-        host => Callable[[], Optional[String]],
-        password => Callable[[], Optional[String[1]]],
-        port => Callable[[], Optional[Integer]],
-        protocol => Callable[[], Optional[String[1]]],
-        user => Callable[[], Optional[String[1]]],
-      }
-    PUPPET
-    implementation_class Bolt::Target
-  else
-    interface <<-PUPPET
-      attributes => {
-        uri => { type => Optional[String[1]], kind => given_or_derived },
-        name => { type => Optional[String[1]] , kind => given_or_derived },
-        safe_name => { type =>  Optional[String[1]], kind => given_or_derived },
-        target_alias => { type => Optional[Variant[String[1], Array[String[1]]]], kind => given_or_derived },
-        config => { type => Optional[Hash[String[1], Data]], kind => given_or_derived },
-        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 }
-      },
-      functions => {
-        host => Callable[[], Optional[String]],
-        password => Callable[[], Optional[String[1]]],
-        port => Callable[[], Optional[Integer]],
-        protocol => Callable[[], Optional[String[1]]],
-        user => Callable[[], Optional[String[1]]],
-      }
-    PUPPET
+  interface <<-PUPPET
+    attributes => {
+      uri => { type => Optional[String[1]], kind => given_or_derived },
+      name => { type => Optional[String[1]] , kind => given_or_derived },
+      safe_name => { type =>  Optional[String[1]], kind => given_or_derived },
+      target_alias => { type => Optional[Variant[String[1], Array[String[1]]]], kind => given_or_derived },
+      config => { type => Optional[Hash[String[1], Data]], kind => given_or_derived },
+      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 }
+    },
+    functions => {
+      host => Callable[[], Optional[String]],
+      password => Callable[[], Optional[String[1]]],
+      port => Callable[[], Optional[Integer]],
+      protocol => Callable[[], Optional[String[1]]],
+      user => Callable[[], Optional[String[1]]],
+    }
+  PUPPET
 
-    implementation_class target_implementation_class
-  end
+  implementation_class target_implementation_class
 end

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

@@ -4,17 +4,17 @@ require 'bolt/error'
 
 # Deep merges a hash of facts with the existing facts on a target.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:add_facts) do
   # @param target A target.
   # @param facts A hash of fact names to values that may include structured facts.
-  # @return The target's new facts or a `Target` object if the `future` flag is set to true
+  # @return A `Target` object.
   # @example Adding facts to a target
   #   add_facts($target, { 'os' => { 'family' => 'windows', 'name' => 'windows' } })
   dispatch :add_facts do
     param 'Target', :target
     param 'Hash', :facts
-    return_type 'Variant[Target, Hash[String, Data]]'
+    return_type 'Target'
   end
 
   def add_facts(target, facts)

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

@@ -4,7 +4,7 @@ require 'bolt/error'
 
 # Adds a target to specified inventory group.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:add_to_group) do
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param group The name of the group to add targets to.

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

@@ -2,15 +2,15 @@
 
 require 'bolt/task'
 
-# Installs the puppet-agent package on targets if needed, then collects facts,
+# Installs the `puppet-agent` package on targets if needed, then collects facts,
 # including any custom facts found in Bolt's modulepath. The package is
 # installed using either the configured plugin or the `task` plugin with the
 # `puppet_agent::install` task.
 #
-# Agent installation will be skipped if the target includes the 'puppet-agent' feature, either as a
+# Agent installation will be skipped if the target includes the `puppet-agent` feature, either as a
 # property of its transport (PCP) or by explicitly setting it as a feature in Bolt's inventory.
 #
-# **NOTE:** Not available in apply block
+# > **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.
   # @example Prepare targets by name.
@@ -83,15 +83,13 @@ Puppet::Functions.create_function(:apply_prep) do
           pool = Concurrent::ThreadPoolExecutor.new
 
           hooks = need_install_targets.map do |t|
-            begin
-              opts = t.plugin_hooks&.fetch('puppet_library').dup
-              plugin_name = opts.delete('plugin')
-              hook = inventory.plugins.get_hook(plugin_name, :puppet_library)
-              { 'target' => t,
-                'hook_proc' => hook.call(opts, t, self) }
-            rescue StandardError => e
-              Bolt::Result.from_exception(t, e)
-            end
+            opts = t.plugin_hooks&.fetch('puppet_library').dup
+            plugin_name = opts.delete('plugin')
+            hook = inventory.plugins.get_hook(plugin_name, :puppet_library)
+            { 'target' => t,
+              'hook_proc' => hook.call(opts, t, self) }
+          rescue StandardError => e
+            Bolt::Result.from_exception(t, e)
           end
 
           hook_errors, ok_hooks = hooks.partition { |h| h.is_a?(Bolt::Result) }

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

@@ -4,7 +4,7 @@
 # output of the block if no errors are raised. Accepts an optional list of
 # error kinds to catch.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:catch_errors) do
   # @param error_types An array of error types to catch
   # @param block The block of steps to catch errors on

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

@@ -2,12 +2,12 @@
 
 require 'bolt/error'
 
-# Raises a Bolt::PlanFailure exception to signal to callers that the plan failed.
+# Raises a `Bolt::PlanFailure` exception to signal to callers that the plan failed.
 #
 # Plan authors should call this function when their plan is not successful. The
-# error may then be caught by another plans run_plan function or in bolt itself
+# error may then be caught by another plans `run_plan` function or in Bolt itself
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:fail_plan) do
   # Fail a plan, generating an exception from the parameters.
   # @param msg An error message.

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

@@ -6,20 +6,21 @@ require 'bolt/task'
 # 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
-# or by directly running the puppet_agent::install task. In order to be able to reference types without
-# string quoting (for example `get_resources($target, Package)` instead of `get_resources($target, 'Package')`)
+# or by directly running the `puppet_agent::install` task. In order to be able to reference types without
+# string quoting (for example `get_resources($target, Package)` instead of `get_resources($target, 'Package')`),
 # run the command `bolt puppetfile generate-types` to generate type references in `$Boldir/.resource_types`.
 #
-#
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:get_resources) do
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param resources A resource type or instance, or an array of such.
+  # @return A result set with a list of hashes representing each resource.
   # @example Collect resource states for packages and a file
   #   get_resources('target1,target2', [Package, File[/etc/puppetlabs]])
   dispatch :get_resources do
     param 'Boltlib::TargetSpec', :targets
     param 'Variant[String, Type[Resource], Array[Variant[String, Type[Resource]]]]', :resources
+    return_type 'ResultSet'
   end
 
   def script_compiler

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

@@ -4,9 +4,7 @@ require 'bolt/error'
 
 # Get a single target from inventory if it exists, otherwise create a new Target.
 #
-# **NOTE:** Calling `get_target('all')` returns an empty array.
-# **NOTE:** Only compatible with inventory v2
-# **NOTE:** Not available in apply block when `future` is true
+# > **Note:** Calling `get_target('all')` returns an empty array.
 Puppet::Functions.create_function(:get_target) do
   # @param name A Target name.
   # @return A single target, either new or from inventory.

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

@@ -3,9 +3,8 @@
 require 'bolt/error'
 
 # Parses common ways of referring to targets and returns an array of Targets.
-# `get_targets('all')` returns an empty array.
 #
-# **NOTE:** Not available in apply block when `future` is true
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:get_targets) do
   # @param names A pattern or array of patterns identifying a set of targets.
   # @return A list of unique Targets resolved from any target URIs and groups.

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

@@ -4,8 +4,8 @@ require 'bolt/error'
 
 # Collects facts based on a list of certnames.
 #
-# * If a node is not found in PuppetDB, it's included in the returned hash with empty facts hash.
-# * Otherwise the node is included in the hash with a value that is a hash of it's facts.
+# If a node is not found in PuppetDB, it's included in the returned hash with an empty facts hash.
+# Otherwise, the node is included in the hash with a value that is a hash of its facts.
 Puppet::Functions.create_function(:puppetdb_fact) do
   # @param certnames Array of certnames.
   # @return A hash of certname to facts hash for each matched Target.

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

@@ -5,9 +5,9 @@ require 'bolt/error'
 # Removes a target from the specified inventory group.
 #
 # The target is removed from all child groups and all parent groups where the target has
-# not been explicitly defined. A target cannot be removed from the 'all' group.
+# not been explicitly defined. A target cannot be removed from the `all` group.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:remove_from_group) do
   # @param target A pattern identifying a single target.
   # @param group The name of the group to remove the target from.

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

@@ -2,7 +2,7 @@
 
 require 'bolt/error'
 
-# Evaulates all _plugin references in a hash and returns the resolved reference data.
+# Evaluates all `_plugin` references in a hash and returns the resolved reference data.
 Puppet::Functions.create_function(:resolve_references) do
   # Resolve references.
   # @param references A hash of reference data to resolve.

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

@@ -5,12 +5,14 @@ require 'bolt/error'
 # Runs a command on the given set of targets and returns the result from each command execution.
 # This function does nothing if the list of targets is empty.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:run_command) do
   # Run a command.
   # @param command A command to run on target.
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
-  # @param options Additional options: '_catch_errors', '_run_as'.
+  # @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.
   # @example Run a command on targets
   #   run_command('hostname', $targets, '_catch_errors' => true)
@@ -25,7 +27,9 @@ Puppet::Functions.create_function(:run_command) do
   # @param command A command to run on target.
   # @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 Additional options: '_catch_errors', '_run_as'.
+  # @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.
   # @example Run a command on targets
   #   run_command('hostname', $targets, 'Get hostname')

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

@@ -4,11 +4,13 @@ require 'bolt/error'
 
 # Runs the `plan` referenced by its name. A plan is autoloaded from `$MODULEROOT/plans`.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction) do
   # Run a plan
   # @param plan_name The plan to run.
-  # @param args Arguments to the plan. Can also include additional options: '_catch_errors', '_run_as'.
+  # @param args A hash of arguments to the plan. Can also include additional options.
+  # @option args [Boolean] _catch_errors Whether to catch raised errors.
+  # @option args [String] _run_as User to run as using privilege escalation.
   # @return [PlanResult] The result of running the plan. Undef if plan does not explicitly return results.
   # @example Run a plan
   #   run_plan('canary', 'command' => 'false', 'targets' => $targets, '_catch_errors' => true)
@@ -19,19 +21,16 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
     return_type 'Boltlib::PlanResult'
   end
 
-  # Run a plan, specifying $nodes or $targets as a positional argument.
+  # Run a plan, specifying `$nodes` or `$targets` as a positional argument.
   #
-  # When running a plan with a $nodes parameter, the second positional argument will always specify
-  # the $nodes parameter. When running a plan with a $targets parameter and no $nodes parameter, the
-  # second positional argument specifies the $targets parameter.
-  #
-  # Deprecation Warning: Starting with Bolt 2.0, a plan with both a $nodes and $targets parameter
-  # cannot specify either parameter using the second positional argument and will result in the plan
-  # failing to run.
+  # > **Note:** When running a plan with both a `$nodes` and `$targets` parameter, and using the second
+  # positional argument, the plan will fail.
   #
   # @param plan_name The plan to run.
-  # @param args Arguments to the plan. Can also include additional options: '_catch_errors', '_run_as'.
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param args A hash of arguments to the plan. Can also include additional options.
+  # @option args [Boolean] _catch_errors Whether to catch raised errors.
+  # @option args [String] _run_as User to run as using privilege escalation.
   # @return [PlanResult] The result of running the plan. Undef if plan does not explicitly return results.
   # @example Run a plan
   #   run_plan('canary', $targets, 'command' => 'false')
@@ -98,7 +97,7 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
       param_acc[param.name] = extract_parameter_types(param.type_expr)&.flatten
     end
 
-    targets_to_param(targets, params, param_types, executor) if targets
+    targets_to_param(targets, params, param_types) if targets
 
     if inventory.version > 1
       params.each do |param, value|
@@ -170,30 +169,15 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
     end
   end
 
-  def targets_to_param(targets, params, param_types, executor)
+  def targets_to_param(targets, params, param_types)
     nodes_param = param_types.include?('nodes')
     targets_param = param_types['targets']&.any? { |p| p.match?(/TargetSpec/) }
 
     # Both a 'TargetSpec $nodes' and 'TargetSpec $targets' parameter are present in the plan
-    # 1.x behavior: Populate $nodes and warn user that this will error in 2.x
-    # 2.x behavior: Error
     if nodes_param && targets_param
-      # rubocop:disable Style/GlobalVars
-      if $future
-        raise ArgumentError,
-              "A plan with both a $nodes and $targets parameter cannot have either parameter specified " \
-              "as the second positional argument to run_plan()."
-      else
-        msg = <<~WARNING
-              Deprecation Warning: A plan with both a $nodes and $targets parameter can only specify
-              the $nodes parameter as the second positional argument to run_plan(). Starting in
-              Bolt 2.0, a plan with both a $nodes and $targets parameter will not be able to specify
-              either parameter as the second positional argument to run_plan() and will result in the
-              plan failing.
-              WARNING
-        executor.deprecation(msg)
-      end
-      # rubocop:enable Style/GlobalVars
+      raise ArgumentError,
+            "A plan with both a $nodes and $targets parameter cannot have either parameter specified " \
+            "as the second positional argument to run_plan()."
     end
 
     # Always populate a $nodes parameter over $targets

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

@@ -3,14 +3,16 @@
 # Uploads the given script to the given set of targets and returns the result of having each target execute the script.
 # This function does nothing if the list of targets is empty.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFunction) do
   # Run a script.
   # @param script Path to a script to run on target. May be an absolute path or a modulename/filename selector for a
   #               file in $MODULEROOT/files.
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
-  # @param options Specify an array of arguments to the 'arguments' key to be passed to the script.
-  #                Additional options: '_catch_errors', '_run_as'.
+  # @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.
   # @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')
@@ -29,8 +31,10 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
   #               file in $MODULEROOT/files.
   # @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 Specify an array of arguments to the 'arguments' key to be passed to the script.
-  #                Additional options: '_catch_errors', '_run_as'.
+  # @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.
   # @return A list of results, one entry per target.
   # @example Run a script
   #   run_script('/var/tmp/myscript', $targets, 'Downloading my application')