bolt 2.20.0 → 2.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a72c179da8e6e3fd3d8f883366e88f98026de00eee08ae2410515b2103a3810d
-  data.tar.gz: 968edc1c0c30a370ed06b1c9bd5498ccaaaa5e15f3c47307cad1e68f2af5dafb
+  metadata.gz: 4a424969e4d64b199e77f75c0d67f2f8d668124dea01c8feaec98f7c8d6acd8a
+  data.tar.gz: c877c94c963b4dcca169b8bad3cf85fe547c1ca9a6050c9554fcc0685cb324b5
 SHA512:
-  metadata.gz: a906282180c5df824978979d8e12da5cbe2f835ccef2ae65f2e2fc892bcfa1514a4f8f76418b866fe9cbfe8ce8f8f28b66306055b7acc67de6a7a2e13bb7edbf
-  data.tar.gz: ee4c33740e8e29ad4b3026e5b75b3f0d29556c92e9277bc34101c5f8acfe80db599389c8544aab5946c6c444502a49ddb515da0a854b5796b0aae54fc0875ffc
+  metadata.gz: 7720901d8ad877de79b073b3d2d845e78845366bd3e556b4e9c7f4c3be7907e4f9bbf95de06a2583fa2b8d773494855bc3ff1d03fbd3a05217afa969caa1b703
+  data.tar.gz: f9f4ffb0512f5be6962497bec3f64f69e58f79862fb0337c7d7d67d8964a124afc01ea99cec2f39c12952943e06006d8bc99bb2651e592b909f599791d2b0b4d

data/Puppetfile

@@ -5,7 +5,7 @@ forge "http://forge.puppetlabs.com"
 moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
-mod 'puppetlabs-service', '1.2.0'
+mod 'puppetlabs-service', '1.3.0'
 mod 'puppetlabs-puppet_agent', '3.2.0'
 mod 'puppetlabs-facts', '1.0.0'
 
@@ -28,6 +28,7 @@ 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'
+mod 'puppetlabs-stdlib', '6.3.0'
 
 # Plugin modules
 mod 'puppetlabs-aws_inventory', '0.5.0'
@@ -42,3 +43,4 @@ mod 'puppetlabs-yaml', '0.2.0'
 mod 'canary', local: true
 mod 'aggregate', local: true
 mod 'puppetdb_fact', local: true
+mod 'secure_env_vars', local: true

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

@@ -11,6 +11,9 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
   # @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.
+  #   This option sets the [run-as user](privilege_escalation.md) for all
+  #   targets whenever Bolt connects to a target. This is set for all functions
+  #   in the called plan, including `run_plan()`.
   # @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)
@@ -31,6 +34,9 @@ Puppet::Functions.create_function(:run_plan, Puppet::Functions::InternalFunction
   # @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.
+  #   This option sets the [run-as user](privilege_escalation.md) for all
+  #   targets whenever Bolt connects to a target. This is set for all functions
+  #   in the called plan, including `run_plan()`.
   # @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')

data/bolt-modules/ctrl/lib/puppet/functions/ctrl/do_until.rb

@@ -4,30 +4,36 @@
 Puppet::Functions.create_function(:'ctrl::do_until') do
   # @param options A hash of additional options.
   # @option options [Numeric] limit The number of times to repeat the block.
+  # @option options [Numeric] interval The number of seconds to wait before repeating the block.
   # @example Run a task until it succeeds
   #   ctrl::do_until() || {
-  #     run_task('test', $target, _catch_errors => true).ok()
+  #     run_task('test', $target, '_catch_errors' => true).ok()
   #   }
-  #
   # @example Run a task until it succeeds or fails 10 times
   #   ctrl::do_until('limit' => 10) || {
-  #     run_task('test', $target, _catch_errors => true).ok()
+  #     run_task('test', $target, '_catch_errors' => true).ok()
+  #   }
+  # @example Run a task and wait 10 seconds before running it again
+  #   ctrl::do_until('interval' => 10) || {
+  #     run_task('test', $target, '_catch_errors' => true).ok()
   #   }
-  #
   dispatch :do_until do
     optional_param 'Hash[String[1], Any]', :options
     block_param
   end
 
-  def do_until(options = { 'limit' => 0 })
+  def do_until(options = {})
     # Send Analytics Report
     Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
 
-    limit = options['limit']
+    limit = options['limit'] || 0
+    interval = options['interval']
+
     i = 0
     until (x = yield)
       i += 1
       break if limit != 0 && i >= limit
+      Kernel.sleep(interval) if interval
     end
     x
   end

data/bolt-modules/dir/lib/puppet/functions/dir/children.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+# Returns an array containing all of the filenames except for "." and ".." in the given directory.
+Puppet::Functions.create_function(:'dir::children', Puppet::Functions::InternalFunction) do
+  # @param dirname Absolute path or Puppet module name.
+  # @return Array of files in the given directory.
+  # @example List filenames from an absolute path.
+  #   dir::children('/home/user/subdir/')
+  # @example List filenames from a Puppet file path.
+  #   dir::children('puppet_agent')
+  dispatch :children do
+    scope_param
+    required_param 'String', :dirname
+    return_type 'Array'
+  end
+
+  def children(scope, dirname)
+    # Send Analytics Report
+    Puppet.lookup(:bolt_executor) {}&.report_function_call(self.class.name)
+    modname, subpath = dirname.split(File::SEPARATOR, 2)
+    mod_path = scope.compiler.environment.module(modname)&.path
+
+    full_mod_path = File.join(mod_path, subpath || '') if mod_path
+
+    # Expand relative to the project directory if path is relative
+    project = Puppet.lookup(:bolt_project_data)
+    pathname = Pathname.new(dirname)
+    full_dir = pathname.absolute? ? dirname : File.expand_path(File.join(project.path, dirname))
+
+    # Sort for testability
+    Dir.children(full_mod_path || full_dir).sort
+  end
+end

data/bolt-modules/out/lib/puppet/functions/out/message.rb

@@ -12,7 +12,7 @@ Puppet::Functions.create_function(:'out::message') do
   # @example Print a message
   #   out::message('Something went wrong')
   dispatch :output_message do
-    param 'String', :message
+    param 'Any', :message
     return_type 'Undef'
   end
 

data/exe/bolt

@@ -4,6 +4,7 @@
 require 'bolt'
 require 'bolt/cli'
 
+Thread.current[:name] ||= 'main'
 cli = Bolt::CLI.new(ARGV)
 begin
   opts = cli.parse

data/guides/inventory.txt

@@ -0,0 +1,19 @@
+TOPIC
+    inventory
+
+DESCRIPTION
+    The inventory describes the targets that you run Bolt commands on, along
+    with any data and configuration for the targets. Targets in an inventory can
+    belong to one or more groups, allowing you to share data and configuration
+    across multiple targets and to specify multiple targets for your Bolt
+    commands without the need to list each target individually.
+
+    In most cases, Bolt loads the inventory from an inventory file in your Bolt
+    project. The inventory file is a YAML file named 'inventory.yaml'. Because
+    Bolt loads the inventory file from a Bolt project, you must have an existing
+    project configuration file named 'bolt-project.yaml' alongside the inventory
+    file.
+
+DOCUMENTATION
+    https://pup.pt/bolt-inventory
+    https://pup.pt/bolt-inventory-reference

data/guides/project.txt

@@ -0,0 +1,22 @@
+TOPIC
+    project
+
+DESCRIPTION
+    A Bolt project is a directory that serves as the launching point for Bolt
+    and allows you to create a shareable orchestration application. Projects
+    typically include a project configuration file, an inventory file, and any
+    content you use in your project workflow, such as tasks and plans.
+
+    When you run Bolt, it runs in the context of a project. If the directory you
+    run Bolt from is not a project, Bolt attempts to find a project by
+    traversing the parent directories. If Bolt is unable to find a project, it
+    runs from the default project, located at '~/.puppetlabs/bolt'.
+
+    A directory is only considered a Bolt project when it has a project
+    configuration file named 'bolt-project.yaml'. Bolt doesn't load project data
+    and content, including inventory files, unless the data and content are part
+    of a project.
+
+DOCUMENTATION
+    https://pup.pt/bolt-projects
+    https://pup.pt/bolt-project-reference

data/lib/bolt/analytics.rb

@@ -72,7 +72,7 @@ module Bolt
 
     def self.load_config(filename, logger)
       if File.exist?(filename)
-        YAML.load_file(filename)
+        Bolt::Util.read_optional_yaml_hash(filename, 'analytics')
       else
         unless ENV['BOLT_DISABLE_ANALYTICS']
           logger.warn <<~ANALYTICS
@@ -161,9 +161,9 @@ module Bolt
         # Handle analytics submission in the background to avoid blocking the
         # app or polluting the log with errors
         Concurrent::Future.execute(executor: @executor) do
-          @logger.debug "Submitting analytics: #{JSON.pretty_generate(params)}"
+          @logger.trace "Submitting analytics: #{JSON.pretty_generate(params)}"
           @http.post(TRACKING_URL, params)
-          @logger.debug "Completed analytics submission"
+          @logger.trace "Completed analytics submission"
         end
       end
 
@@ -215,13 +215,13 @@ module Bolt
       end
 
       def screen_view(screen, **_kwargs)
-        @logger.debug "Skipping submission of '#{screen}' screenview because analytics is disabled"
+        @logger.trace "Skipping submission of '#{screen}' screenview because analytics is disabled"
       end
 
       def report_bundled_content(mode, name); end
 
       def event(category, action, **_kwargs)
-        @logger.debug "Skipping submission of '#{category} #{action}' event because analytics is disabled"
+        @logger.trace "Skipping submission of '#{category} #{action}' event because analytics is disabled"
       end
 
       def finish; end

data/lib/bolt/applicator.rb

@@ -27,7 +27,7 @@ module Bolt
       @hiera_config = hiera_config ? validate_hiera_config(hiera_config) : nil
       @apply_settings = apply_settings || {}
 
-      @pool = Concurrent::ThreadPoolExecutor.new(max_threads: max_compiles)
+      @pool = Concurrent::ThreadPoolExecutor.new(name: 'apply', max_threads: max_compiles)
       @logger = Logging.logger[self]
     end
 
@@ -217,6 +217,7 @@ module Bolt
       r = @executor.log_action(description, targets) do
         futures = targets.map do |target|
           Concurrent::Future.execute(executor: @pool) do
+            Thread.current[:name] ||= Thread.current.name
             @executor.with_node_logging("Compiling manifest block", [target]) do
               compile(target, scope)
             end
@@ -300,7 +301,7 @@ module Bolt
 
         files.each do |file|
           tar_path = Pathname.new(file).relative_path_from(parent)
-          @logger.debug("Packing plugin #{file} to #{tar_path}")
+          @logger.trace("Packing plugin #{file} to #{tar_path}")
           stat = File.stat(file)
           content = File.binread(file)
           output.tar.add_file_simple(
@@ -314,7 +315,7 @@ module Bolt
       end
 
       duration = Time.now - start_time
-      @logger.debug("Packed plugins in #{duration * 1000} ms")
+      @logger.trace("Packed plugins in #{duration * 1000} ms")
 
       output.close
       Base64.encode64(sio.string)

data/lib/bolt/bolt_option_parser.rb

@@ -25,7 +25,7 @@ module Bolt
       when 'command'
         case action
         when 'run'
-          { flags: ACTION_OPTS,
+          { flags: ACTION_OPTS + %w[env-var],
             banner: COMMAND_RUN_HELP }
         else
           { flags: OPTIONS[:global],
@@ -61,11 +61,17 @@ module Bolt
           { flags: OPTIONS[:global],
             banner: GROUP_HELP }
         end
+      when 'guide'
+        { flags: OPTIONS[:global] + %w[format],
+          banner: GUIDE_HELP }
       when 'plan'
         case action
         when 'convert'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters],
             banner: PLAN_CONVERT_HELP }
+        when 'new'
+          { flags: OPTIONS[:global] + %w[configfile project],
+            banner: PLAN_NEW_HELP }
         when 'run'
           { flags: ACTION_OPTS + %w[params compile-concurrency tmpdir hiera-config],
             banner: PLAN_RUN_HELP }
@@ -82,7 +88,7 @@ module Bolt
           { flags: OPTIONS[:global] + %w[modules],
             banner: PROJECT_INIT_HELP }
         when 'migrate'
-          { flags: OPTIONS[:global] + %w[inventoryfile boltdir configfile],
+          { flags: OPTIONS[:global] + %w[inventoryfile project configfile],
             banner: PROJECT_MIGRATE_HELP }
         else
           { flags: OPTIONS[:global],
@@ -106,7 +112,7 @@ module Bolt
       when 'script'
         case action
         when 'run'
-          { flags: ACTION_OPTS + %w[tmpdir],
+          { flags: ACTION_OPTS + %w[tmpdir env-var],
             banner: SCRIPT_RUN_HELP }
         else
           { flags: OPTIONS[:global],
@@ -159,15 +165,19 @@ module Bolt
       SUBCOMMANDS
           apply             Apply Puppet manifest code
           command           Run a command remotely
-          file              Upload a local file or directory
+          file              Copy files between the controller and targets
           group             Show the list of groups in the inventory
+          guide             View guides for Bolt concepts and features
           inventory         Show the list of targets an action would run on
-          plan              Convert, show, and run Bolt plans
+          plan              Convert, create, show, and run Bolt plans
           project           Create and migrate Bolt projects
           puppetfile        Install and list modules and generate type references
           script            Upload a local script and run it remotely
           secret            Create encryption keys and encrypt and decrypt values
           task              Show and run Bolt tasks
+
+      GUIDES
+          For a list of guides on Bolt's concepts and features, run 'bolt guide'.
     HELP
 
     APPLY_HELP = <<~HELP
@@ -286,6 +296,26 @@ module Bolt
           Show the list of groups in the inventory.
     HELP
 
+    GUIDE_HELP = <<~HELP
+      NAME
+          guide
+
+      USAGE
+          bolt guide [topic] [options]
+
+      DESCRIPTION
+          View guides for Bolt's concepts and features.
+
+          Omitting a topic will display a list of available guides,
+          while providing a topic will display the relevant guide.
+
+      EXAMPLES
+          View a list of available guides
+            bolt guide
+          View the 'project' guide page
+            bolt guide project
+    HELP
+
     INVENTORY_HELP = <<~HELP
       NAME
           inventory
@@ -319,10 +349,11 @@ module Bolt
           bolt plan <action> [parameters] [options]
 
       DESCRIPTION
-          Convert, show, and run Bolt plans.
+          Convert, create, show, and run Bolt plans.
 
       ACTIONS
           convert       Convert a YAML plan to a Bolt plan
+          new           Create a new plan in the current project
           run           Run a plan on the specified targets
           show          Show available plans and plan documentation
     HELP
@@ -345,6 +376,20 @@ module Bolt
           bolt plan convert path/to/plan/myplan.yaml
     HELP
 
+    PLAN_NEW_HELP = <<~HELP
+      NAME
+          new
+      
+      USAGE
+          bolt plan new <plan> [options]
+      
+      DESCRIPTION
+          Create a new plan in the current project.
+
+      EXAMPLES
+          bolt plan new myproject::myplan
+    HELP
+
     PLAN_RUN_HELP = <<~HELP
       NAME
           run
@@ -402,19 +447,18 @@ module Bolt
           init
 
       USAGE
-          bolt project init [directory] [options]
+          bolt project init [name] [options]
 
       DESCRIPTION
-          Create a new Bolt project.
+          Create a new Bolt project in the current working directory.
 
-          Specify a directory to create a Bolt project in. Defaults to the
-          curent working directory.
+          Specify a name for the Bolt project. Defaults to the basename of the current working directory.
 
       EXAMPLES
-          Create a new Bolt project in the current working directory.
+          Create a new Bolt project using the directory as the project name.
             bolt project init
-          Create a new Bolt project at a specified path.
-            bolt project init ~/path/to/project
+          Create a new Bolt project with a specified name.
+            bolt project init myproject
           Create a new Bolt project with existing modules.
             bolt project init --modules puppetlabs-apt,puppetlabs-ntp
     HELP
@@ -427,10 +471,7 @@ module Bolt
           bolt project migrate [options]
 
       DESCRIPTION
-          Migrate a Bolt project to the latest version.
-
-          Loads a Bolt project's inventory file and migrates it to the latest version. The
-          inventory file is modified in place and will not preserve comments or formatting.
+          Migrate a Bolt project to use current best practices and the latest version of configuration files.
     HELP
 
     PUPPETFILE_HELP = <<~HELP
@@ -676,9 +717,9 @@ module Bolt
         @options[:password] = password
       end
       define('--password-prompt', 'Prompt for user to input password') do |_password|
-        STDERR.print "Please enter your password: "
-        @options[:password] = STDIN.noecho(&:gets).chomp
-        STDERR.puts
+        $stderr.print "Please enter your password: "
+        @options[:password] = $stdin.noecho(&:gets).chomp
+        $stderr.puts
       end
       define('--private-key KEY', 'Path to private ssh key to authenticate with') do |key|
         @options[:'private-key'] = File.expand_path(key)
@@ -702,9 +743,9 @@ module Bolt
         @options[:'sudo-password'] = password
       end
       define('--sudo-password-prompt', 'Prompt for user to input escalation password') do |_password|
-        STDERR.print "Please enter your privilege escalation password: "
-        @options[:'sudo-password'] = STDIN.noecho(&:gets).chomp
-        STDERR.puts
+        $stderr.print "Please enter your privilege escalation password: "
+        @options[:'sudo-password'] = $stdin.noecho(&:gets).chomp
+        $stderr.puts
       end
       define('--sudo-executable EXEC', "Specify an executable for running as another user.",
              "This option is experimental.") do |exec|
@@ -761,6 +802,15 @@ module Bolt
         @options[:'save-rerun'] = save
       end
 
+      separator "\nREMOTE ENVIRONMENT OPTIONS"
+      define('--env-var ENVIRONMENT_VARIABLES', 'Environment variables to set on the target') do |envvar|
+        unless envvar.include?('=')
+          raise Bolt::CLIError, "Environment variables must be specified using 'myenvvar=key' format"
+        end
+        @options[:env_vars] ||= {}
+        @options[:env_vars].store(*envvar.split('=', 2))
+      end
+
       separator "\nTRANSPORT OPTIONS"
       define('--transport TRANSPORT', TRANSPORTS.keys.map(&:to_s),
              "Specify a default transport: #{TRANSPORTS.keys.join(', ')}") do |t|
@@ -837,7 +887,7 @@ module Bolt
       end
       define('--log-level LEVEL',
              "Set the log level for the console. Available options are",
-             "debug, info, notice, warn, error, fatal, any.") do |level|
+             "trace, debug, info, warn, error, fatal, any.") do |level|
         @options[:log] = { 'console' => { 'level' => level } }
       end
       define('--plugin PLUGIN', 'Select the plugin to use') do |plug|
@@ -878,7 +928,7 @@ module Bolt
         file = value.sub(/^@/, '')
         read_arg_file(file)
       elsif value == '-'
-        STDIN.read
+        $stdin.read
       else
         value
       end