bolt 2.42.0 → 3.3.0

data/lib/bolt_spec/plans.rb

@@ -5,119 +5,11 @@ require 'bolt_spec/plans/mock_executor'
 require 'bolt/pal'
 
 # These helpers are intended to be used for plan unit testing without calling
-# out to target nodes. It uses the BoltContext helper to set up a mock executor
+# out to targets. It uses the BoltContext helper to set up a mock executor
 # which allows calls to run_* functions to be stubbed for testing. The context
 # helper also loads Bolt datatypes and plan functions to be used by the code
 # being tested.
 #
-# Stub matching
-#
-# Stubs match invocations of run_* functions by default matching any call but
-# with_targets and with_params helpers can further restrict the stub to match
-# more exact invocations. It's possible a call to run_* could match multiple
-# stubs. In this case the mock executor will first check for stubs specifically
-# matching the task being run after which it will use the last stub that
-# matched
-#
-#
-# allow vs expect
-#
-# Stubs have two general modes bases on whether the test is making assertions
-# on whether function was called. Allow stubs allow the run_* invocation  to
-# be called any number of times while expect stubs will fail if no run_*
-# invocation matches them. The be_called_times(n) stub method can be used to
-# ensure an allow stub is not called more than n times or that an expect stub
-# is called exactly n times.
-#
-# Configuration
-#
-#  To configure Puppet and Bolt at the beginning of tests, add the following
-#  line to your spec_helper.rb:
-#
-#  BoltSpec::Plans.init
-#
-#  By default the plan helpers use the modulepath set up for rspec-puppet and
-#  an otherwise empty bolt config and inventory. To create your own values for
-#  these override the modulepath, config, or inventory methods.
-#
-# Sub-plan Execution
-#
-#  When testing a plan, often times those plans call other plans in order to
-#  build complex workflows. To support this we offer running in two different
-#  modes:
-#    execute_any_plan (default) - This mode will execute any plan that is encountered
-#      without having to be stubbed/mocked. This default mode allows for plan control
-#      flow to behave as normal. If you choose to stub/mock out a sub-plan in this mode
-#      that will be honored and the sub-plan will not be executed. We will use the modifiers
-#      on the stub to check for the conditions specified (example: be_called_times(3))
-#
-#    execute_no_plan - This mode will not execute a plans that it encounters. Instead, when
-#      a plan is encountered it will throw an error unless the plan is mocked out. This
-#      mode is useful for ensuring that there are no plans called that you do not expect.
-#      This plan requires authors to mock out all sub-plans that may be invoked when running
-#      tests.
-#
-#  TODO:
-#  - Allow description based stub matching
-#  - Better testing of plan errors
-#  - Better error collection around call counts. Show what stubs exists and more than a single failure
-#  - Allow stubbing with a block(at the double level? As a matched stub?)
-#  - package code so that it can be used for testing modules outside of this repo
-#  - set subject from describe and provide matchers similar to rspec puppets function tests
-#  - Allow specific plans to be executed when running in execute_no_plan mode.
-#
-#  MAYBE TODO?:
-#  - validate call expectations at the end of the example instead of in run_plan
-#  - resultset matchers to help testing canary like plans?
-#  - inventory matchers to help testing plans that change inventory
-#
-# Flags:
-# - execute_any_plan: execute any plan that is encountered unless it is mocked (default)
-# - execute_no_plan: throw an error if a plan is encountered that is not stubbed
-#
-# Stubs:
-# - allow_command(cmd), expect_command(cmd): expect the exact command
-# - allow_plan(plan), expect_plan(plan): expect the named plan
-# - allow_script(script), expect_script(script): expect the script as <module>/path/to/file
-# - allow_task(task), expect_task(task): expect the named task
-# - allow_download(file), expect_download(file): expect the identified source file
-# - allow_upload(file), expect_upload(file): expect the identified source file
-# - allow_apply_prep: allows `apply_prep` to be invoked in the plan but does not allow modifiers
-# - allow_apply: allows `apply` to be invoked in the plan but does not allow modifiers
-# - allow_out_message, expect_out_message: expect a message to be passed to out::message (only modifiers are
-#   be_called_times(n), with_params(params), and not_be_called)
-#
-# Stub modifiers:
-# - be_called_times(n): if allowed, fail if the action is called more than 'n' times
-#                       if expected, fail unless the action is called 'n' times
-# - not_be_called: fail if the action is called
-# - with_targets(targets): target or list of targets that you expect to be passed to the action
-#                          plan: does not support this modifier
-# - with_params(params): list of params and metaparams (or options) that you expect to be passed to the action.
-#                        Corresponds to the action's last argument.
-# - with_destination(dest): for upload_file and download_file, the expected destination path
-# - always_return(value): return a Bolt::ResultSet of Bolt::Result objects with the specified value Hash
-#                         plan: returns a Bolt::PlanResult with the specified value with a status of 'success'
-#                         command and script: only accept 'stdout' and 'stderr' keys
-#                         upload: does not support this modifier
-#                         download: does not support this modifier
-# - return_for_targets(targets_to_values): return a Bolt::ResultSet of Bolt::Result objects from the Hash mapping
-#                                          targets to their value Hashes
-#                                          command and script: only accept 'stdout' and 'stderr' keys
-#                                          upload: does not support this modifier
-#                                          download: does not support this modifier
-#                                          plan: does not support this modifier
-# - return(&block): invoke the block to construct a Bolt::ResultSet. The blocks parameters differ based on action
-#                   command: `{ |targets:, command:, params:| ... }`
-#                   plan: `{ |plan:, params:| ... }`
-#                   script: `{ |targets:, script:, params:| ... }`
-#                   task: `{ |targets:, task:, params:| ... }`
-#                   upload: `{ |targets:, source:, destination:, params:| ... }`
-#                   download: `{ |targets:, source:, destination:, params:| ... }`
-# - error_with(err): return a failing Bolt::ResultSet, with Bolt::Result objects with the identified err hash
-#                    plans will throw a Bolt::PlanFailure that will be returned as the value of
-#                    the Bolt::PlanResult object with a status of 'failure'.
-#
 # Example:
 #   describe "my_plan" do
 #     it 'should return' do

data/lib/bolt_spec/plans/action_stubs.rb

@@ -177,7 +177,7 @@ module BoltSpec
         if data['msg'] && data['kind'] && (data.keys - %w[msg kind details issue_code]).empty?
           @data[:default] = clazz.new(data['msg'], data['kind'], data['details'], data['issue_code'])
         else
-          $stderr.puts "In the future 'error_with()' may require msg and kind, and " \
+          $stderr.puts "In the future 'error_with()' might require msg and kind, and " \
                       "optionally accept only details and issue_code."
           @data[:default] = data
         end

data/lib/bolt_spec/plans/mock_executor.rb

@@ -214,8 +214,12 @@ module BoltSpec
 
       def report_bundled_content(_mode, _name); end
 
+      def report_file_source(_plan_function, _source); end
+
       def report_apply(_statements, _resources); end
 
+      def report_yaml_plan(_plan); end
+
       def publish_event(event)
         if event[:type] == :message
           unless @stub_out_message

data/libexec/bolt_catalog

@@ -56,7 +56,7 @@ when "compile"
               else
                 e.message
               end
-    puts({ message: message }.to_json)
+    puts({ message: message, backtrace: e.backtrace }.to_json)
     exit 1
   rescue StandardError => e
     puts({ message: e.message }.to_json)

data/modules/aggregate/plans/count.pp

@@ -1,3 +1,24 @@
+# @summary
+#   Run a task, command, or script on targets and aggregate the results as
+#   a count of targets for each value of a key.
+#
+# This plan accepts an action and a list of targets. The action can be the name
+# of a task, a script, or a command to run. It will run the action on the
+# targets and aggregate the key/value pairs in each Result into a hash, mapping
+# the keys to a hash of each distinct value and how many targets returned that
+# value for the key.
+#
+# @param command
+#   The command to run. Mutually exclusive with script and task.
+# @param script
+#   The path to the script to run. Mutually exclusive with command and task.
+# @param task
+#   The name of the task to run. Mutually exclusive with command and script.
+# @param targets
+#   The list of targets to run the action on.
+# @param params
+#   A hash of parameters and options to pass to the `run_*` function
+#   associated with the action (e.g. run_task).
 plan aggregate::count(
   Optional[String[0]] $task = undef,
   Optional[String[0]] $command = undef,

data/modules/aggregate/plans/targets.pp

@@ -1,3 +1,24 @@
+# @summary
+#   Run a task, command, or script on targets and aggregate the results as
+#   the list of targets for each value of a key in the results.
+#
+# This plan accepts an action and a list of targets. The action can be the name
+# of a task, a script, or a command to run. It will run the action on the
+# targets and aggregate the key/value pairs in each Result into a hash, mapping
+# the keys to a hash of each distinct value and a list of targets returning that
+# value.
+#
+# @param command
+#   The command to run. Mutually exclusive with script and task.
+# @param script
+#   The path to the script to run. Mutually exclusive with command and task.
+# @param task
+#   The name of the task to run. Mutually exclusive with command and script.
+# @param targets
+#   The list of targets to run the action on.
+# @param params
+#   A hash of parameters and options to pass to the `run_*` function
+#   associated with the action (e.g. run_task).
 plan aggregate::targets(
   Optional[String[0]] $task = undef,
   Optional[String[0]] $command = undef,

data/modules/puppet_connect/plans/test_input_data.pp

@@ -0,0 +1,67 @@
+# @summary
+#   Tests that the provided Puppet Connect input data is complete, meaning that all consuming inventory targets are connectable.
+#
+# This plan should only be used as part of the copy-pastable "test input data"
+# workflow specified in the Puppet Connect docs.
+#
+# @param targets
+#   The set of targets to test. Usually this should be 'all', the default.
+#
+# @return ResultSet the result of invoking the 'is connectable?' query on all
+# the targets. Note that this query currently consists of running the 'echo'
+# command.
+#
+plan puppet_connect::test_input_data(TargetSpec $targets = 'all') {
+  $targs = get_targets($targets)
+  $targs.each |$target| {
+    case $target.transport {
+      'ssh': {
+        $private_key_config = dig($target.config, 'ssh', 'private-key')
+        if $private_key_config =~ String {
+          $msg = @("END")
+            The SSH private key of the ${$target} target points to a filepath on disk,
+            which is not allowed in Puppet Connect. Instead, the private key contents must
+            be specified and this should be done via the PuppetConnectData plugin. Below is
+            an example of a Puppet Connect-compatible specification of the private-key. First,
+            we start with the inventory file:
+              ...
+              private-key:
+                _plugin: puppet_connect_data
+                key: ssh_private_key
+              ...
+
+            Next is the corresponding entry in the input data file:
+              ...
+              ssh_private_key:
+                key-data:
+                  <private_key_contents>
+              ...
+            | END
+
+          out::message($msg)
+          fail_plan("The SSH private key of the ${$target} target points to a filepath on disk")
+        }
+
+        # Disable SSH autoloading to prevent false positive results
+        # (input data is wrong but target is still connectable due
+        # to autoloaded config)
+        set_config($target, ['ssh', 'load-config'], false)
+        # Maintain configuration parity with Puppet Connect to improve
+        # the reliability of our test
+        set_config($target, ['ssh', 'host-key-check'], false)
+      }
+      'winrm': {
+        # Maintain configuration parity with Puppet Connect
+        set_config($target, ['winrm', 'ssl'], false)
+        set_config($target, ['winrm', 'ssl-verify'], false)
+      }
+      default: {
+        fail_plan("Inventory contains target ${target} with unsupported transport, must be ssh or winrm")
+      }
+    }
+  }
+  # The SSH/WinRM transports will report an 'unknown host' error for targets where
+  # 'host' is unknown so run_command's implementation will take care of raising that
+  # error for us.
+  return run_command('echo Connected', $targs)
+}

data/modules/puppetdb_fact/plans/init.pp

@@ -1,3 +1,13 @@
+# @summary
+#   Collect facts for the specified targets from PuppetDB and store them
+#   on the Targets.
+#
+# This plan accepts a list of targets to collect facts for from the configured
+# PuppetDB connection. After collecting facts, they are stored on each target's
+# Target object. The updated facts can then be accessed using `$target.facts`.
+#
+# @param targets
+#   The targets to collect facts for.
 plan puppetdb_fact(TargetSpec $targets) {
   $targs = get_targets($targets)
   $certnames = $targs.map |$target| { $target.host }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 2.42.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-01-11 00:00:00.000000000 Z
+date: 2021-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -184,14 +184,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: puppet
   requirement: !ruby/object:Gem::Requirement
@@ -350,16 +350,16 @@ dependencies:
   name: puppetlabs_spec_helper
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<="
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: 2.15.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<="
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: 2.15.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -467,6 +467,7 @@ files:
 - lib/bolt/config/transport/base.rb
 - lib/bolt/config/transport/docker.rb
 - lib/bolt/config/transport/local.rb
+- lib/bolt/config/transport/lxd.rb
 - lib/bolt/config/transport/options.rb
 - lib/bolt/config/transport/orch.rb
 - lib/bolt/config/transport/remote.rb
@@ -523,6 +524,7 @@ files:
 - lib/bolt/plugin/env_var.rb
 - lib/bolt/plugin/module.rb
 - lib/bolt/plugin/prompt.rb
+- lib/bolt/plugin/puppet_connect_data.rb
 - lib/bolt/plugin/puppetdb.rb
 - lib/bolt/plugin/task.rb
 - lib/bolt/project.rb
@@ -554,6 +556,8 @@ files:
 - lib/bolt/transport/docker/connection.rb
 - lib/bolt/transport/local.rb
 - lib/bolt/transport/local/connection.rb
+- lib/bolt/transport/lxd.rb
+- lib/bolt/transport/lxd/connection.rb
 - lib/bolt/transport/orch.rb
 - lib/bolt/transport/orch/connection.rb
 - lib/bolt/transport/remote.rb
@@ -608,12 +612,12 @@ files:
 - modules/aggregate/lib/puppet/functions/aggregate/nodes.rb
 - modules/aggregate/lib/puppet/functions/aggregate/targets.rb
 - modules/aggregate/plans/count.pp
-- modules/aggregate/plans/nodes.pp
 - modules/aggregate/plans/targets.pp
 - modules/canary/lib/puppet/functions/canary/merge.rb
 - modules/canary/lib/puppet/functions/canary/random_split.rb
 - modules/canary/lib/puppet/functions/canary/skip.rb
 - modules/canary/plans/init.pp
+- modules/puppet_connect/plans/test_input_data.pp
 - modules/puppetdb_fact/plans/init.pp
 homepage: https://github.com/puppetlabs/bolt
 licenses:

data/modules/aggregate/plans/nodes.pp

@@ -1,36 +0,0 @@
-plan aggregate::nodes(
-  Optional[String[0]] $task = undef,
-  Optional[String[0]] $command = undef,
-  Optional[String[0]] $script = undef,
-  TargetSpec $nodes,
-  Hash[String, Data] $params = {}
-) {
-
-  # Validation
-  $type_count = [$task, $command, $script].reduce(0) |$acc, $v| {
-    if ($v) {
-      $acc + 1
-    } else {
-      $acc
-    }
-  }
-
-  if ($type_count == 0) {
-    fail_plan("Must specify a command, script, or task to run", 'aggregate/invalid-params')
-  }
-
-  if ($type_count > 1) {
-    fail_plan("Must specify only one command, script, or task to run", 'aggregate/invalid-params')
-  }
-
-  $res = if ($task) {
-    run_task($task, $nodes, $params)
-  } elsif ($command) {
-    run_command($command, $nodes, $params)
-  } elsif ($script) {
-    run_script($script, $nodes, $params)
-  }
-
-  return aggregate::nodes($res)
-}
-