bolt 2.21.0 → 2.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef2991c1d3979e03b9070dc168be0e8c44c309914fd7eb02badc60e5b5d907bf
-  data.tar.gz: 9508d434488486b8b16d062f910f6d3bcf8d7b3e89121ccb8033dd393a7a21db
+  metadata.gz: 60e995704052fee2778474c532df844e51ca0888017e28c883866e6b61a9678f
+  data.tar.gz: 8133b33137d67ba8880270f4ed20aa8346e13b2aa7ae2b0c390e3fbbba660172
 SHA512:
-  metadata.gz: 351084ca010d6f3d051a588e0d216f07d32473026703378dd7003c9f71f411fa2499926d4e1c6272df55cffc8eeb360fbc6fff4c5a0930c14cba006dfbf3874c
-  data.tar.gz: eef7d1b6b0dfe5584bd216bb5ebe421b61b9e25a4131509cf310f33fc75f7a3afa072e919215eefadb43ac7415cdd51546e6b634daf53d8a7a568366bb31ee68
+  metadata.gz: a057aebe5bd7ce01a8369f3c7a05371f0dab79143cd465f6bd2f0a0ad23fe897fcff6624d03f07ead07b86c888512166232182c294cd1188fcd8fb45b55f463d
+  data.tar.gz: 4c30348d86636398f25568dcd77af25e6eb8e54af5c9ce44125a110b8089c15415a4a051aa8aac066f7404f9ca7faf253dd69e350780ef8d24e34f385c1dd8de

data/lib/bolt/bolt_option_parser.rb

@@ -66,6 +66,9 @@ module Bolt
         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 }
@@ -159,10 +162,10 @@ 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
           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
@@ -319,10 +322,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 +349,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

data/lib/bolt/catalog.rb

@@ -76,7 +76,15 @@ module Bolt
       target = request['target']
       plan_vars = shadow_vars('plan', request['plan_vars'], target['facts'])
       target_vars = shadow_vars('target', target['variables'], target['facts'])
-      topscope_vars = target_vars.merge(plan_vars)
+
+      # Merge plan vars with target vars, while maintaining the order of the plan
+      # vars. It's critical that the order of plan vars is not changed, as Puppet
+      # will deserialize the variables in the order they appear. Variables may
+      # contain local references to variables that appear earlier in a plan. If
+      # these variables are moved before the variable they reference, Puppet will
+      # be unable to deserialize the data and raise an error.
+      topscope_vars = target_vars.reject { |k, _v| plan_vars.key?(k) }.merge(plan_vars)
+
       env_conf = { modulepath: request['modulepath'],
                    facts: target['facts'],
                    variables: topscope_vars }

data/lib/bolt/cli.rb

@@ -31,7 +31,7 @@ module Bolt
     COMMANDS = { 'command' => %w[run],
                  'script' => %w[run],
                  'task' => %w[show run],
-                 'plan' => %w[show run convert],
+                 'plan' => %w[show run convert new],
                  'file' => %w[download upload],
                  'puppetfile' => %w[install show-modules generate-types],
                  'secret' => %w[encrypt decrypt createkeys],
@@ -283,6 +283,10 @@ module Bolt
         raise Bolt::CLIError, "Must specify a value to #{options[:action]}"
       end
 
+      if options[:subcommand] == 'plan' && options[:action] == 'new' && !options[:object]
+        raise Bolt::CLIError, "Must specify a plan name."
+      end
+
       if options.key?(:debug) && options.key?(:log)
         raise Bolt::CLIError, "Only one of '--debug' or '--log-level' may be specified"
       end
@@ -350,19 +354,11 @@ module Bolt
       # Initialize inventory and targets. Errors here are better to catch early.
       # options[:target_args] will contain a string/array version of the targetting options this is passed to plans
       # options[:targets] will contain a resolved set of Target objects
-      unless options[:subcommand] == 'puppetfile' ||
-             options[:subcommand] == 'secret' ||
-             options[:subcommand] == 'project' ||
-             options[:action] == 'show' ||
-             options[:action] == 'convert'
+      unless %w[project puppetfile secret].include?(options[:subcommand]) ||
+             %w[convert new show].include?(options[:action])
         update_targets(options)
       end
 
-      if options[:action] == 'convert'
-        convert_plan(options[:object])
-        return 0
-      end
-
       screen = "#{options[:subcommand]}_#{options[:action]}"
       # submit a different screen for `bolt task show` and `bolt task show foo`
       if options[:action] == 'show' && options[:object]
@@ -414,6 +410,9 @@ module Bolt
       when 'show-modules'
         list_modules
         return 0
+      when 'convert'
+        convert_plan(options[:object])
+        return 0
       end
 
       message = 'There may be processes left executing on some nodes.'
@@ -431,7 +430,12 @@ module Bolt
           code = migrate_project
         end
       when 'plan'
-        code = run_plan(options[:object], options[:task_options], options[:target_args], options)
+        case options[:action]
+        when 'new'
+          code = new_plan(options[:object])
+        when 'run'
+          code = run_plan(options[:object], options[:task_options], options[:target_args], options)
+        end
       when 'puppetfile'
         case options[:action]
         when 'generate-types'
@@ -551,6 +555,118 @@ module Bolt
       outputter.print_groups(groups)
     end
 
+    def new_plan(plan_name)
+      @logger.warn("Command 'bolt plan new' is experimental and subject to changes.")
+
+      if config.project.name.nil?
+        raise Bolt::Error.new(
+          "Project directory '#{config.project.path}' is not a named project. Unable to create "\
+          "a project-level plan. To name a project, set the 'name' key in the 'bolt-project.yaml' "\
+          "configuration file.",
+          "bolt/unnamed-project-error"
+        )
+      end
+
+      if plan_name !~ Bolt::Module::CONTENT_NAME_REGEX
+        message = <<~MESSAGE.chomp
+          Invalid plan name '#{plan_name}'. Plan names are composed of one or more name segments
+          separated by double colons '::'.
+          
+          Each name segment must begin with a lowercase letter, and may only include lowercase
+          letters, digits, and underscores.
+          
+          Examples of valid plan names:
+              - #{config.project.name}
+              - #{config.project.name}::my_plan
+        MESSAGE
+
+        raise Bolt::ValidationError, message
+      end
+
+      prefix, *name_segments, basename = plan_name.split('::')
+
+      # If the plan name is just the project name, then create an 'init' plan.
+      # Otherwise, use the last name segment for the plan's filename.
+      basename ||= 'init'
+
+      unless prefix == config.project.name
+        message = "First segment of plan name '#{plan_name}' must match project name '#{config.project.name}'. "\
+                  "Did you mean '#{config.project.name}::#{plan_name}'?"
+
+        raise Bolt::ValidationError, message
+      end
+
+      dir_path = config.project.plans_path.join(*name_segments)
+
+      %w[pp yaml].each do |ext|
+        next unless (path = config.project.plans_path + "#{basename}.#{ext}").exist?
+        raise Bolt::Error.new(
+          "A plan with the name '#{plan_name}' already exists at '#{path}', nothing to do.",
+          'bolt/existing-plan-error'
+        )
+      end
+
+      begin
+        FileUtils.mkdir_p(dir_path)
+      rescue Errno::EEXIST => e
+        raise Bolt::Error.new(
+          "#{e.message}; unable to create plan directory '#{dir_path}'",
+          'bolt/existing-file-error'
+        )
+      end
+
+      plan_path = dir_path + "#{basename}.yaml"
+
+      plan_template = <<~PLAN
+        # This is the structure of a simple plan. To learn more about writing
+        # YAML plans, see the documentation: http://pup.pt/bolt-yaml-plans
+
+        # The description sets the description of the plan that will appear
+        # in 'bolt plan show' output.
+        description: A plan created with bolt plan new
+
+        # The parameters key defines the parameters that can be passed to
+        # the plan.
+        parameters:
+          targets:
+            type: TargetSpec
+            description: A list of targets to run actions on
+            default: localhost
+
+        # The steps key defines the actions the plan will take in order.
+        steps:
+          - message: Hello from #{plan_name}
+          - name: command_step
+            command: whoami
+            targets: $targets
+
+        # The return key sets the return value of the plan.
+        return: $command_step
+      PLAN
+
+      begin
+        File.write(plan_path, plan_template)
+      rescue Errno::EACCES => e
+        raise Bolt::FileError.new(
+          "#{e.message}; unable to create plan",
+          plan_path
+        )
+      end
+
+      output = <<~OUTPUT
+        Created plan '#{plan_name}' at '#{plan_path}'
+
+        Show this plan with:
+            bolt plan show #{plan_name}
+        Run this plan with:
+            bolt plan run #{plan_name}
+      OUTPUT
+
+      outputter.print_message(output)
+
+      0
+    end
+
     def run_plan(plan_name, plan_arguments, nodes, options)
       unless nodes.empty?
         if plan_arguments['nodes'] || plan_arguments['targets']

data/lib/bolt/module.rb

@@ -3,7 +3,8 @@
 # Is this Bolt::Pobs::Module?
 module Bolt
   class Module
-    MODULE_NAME_REGEX = /\A[a-z][a-z0-9_]*\z/.freeze
+    CONTENT_NAME_REGEX = /\A[a-z][a-z0-9_]*(::[a-z][a-z0-9_]*)*\z/.freeze
+    MODULE_NAME_REGEX  = /\A[a-z][a-z0-9_]*\z/.freeze
 
     def self.discover(modulepath)
       modulepath.each_with_object({}) do |path, mods|

data/lib/bolt/project.rb

@@ -3,6 +3,7 @@
 require 'pathname'
 require 'bolt/config'
 require 'bolt/pal'
+require 'bolt/module'
 
 module Bolt
   class Project
@@ -17,7 +18,7 @@ module Bolt
 
     attr_reader :path, :data, :config_file, :inventory_file, :modulepath, :hiera_config,
                 :puppetfile, :rerunfile, :type, :resource_types, :warnings, :project_file,
-                :deprecations, :downloads
+                :deprecations, :downloads, :plans_path
 
     def self.default_project
       create_project(File.expand_path(File.join('~', '.puppetlabs', 'bolt')), 'user')
@@ -82,6 +83,7 @@ module Bolt
       @resource_types = @path + '.resource_types'
       @type = type
       @downloads = @path + 'downloads'
+      @plans_path = @path + 'plans'
 
       tc = Bolt::Config::INVENTORY_OPTIONS.keys & raw_data.keys
       if tc.any?
@@ -138,11 +140,9 @@ module Bolt
 
     def validate
       if name
-        name_regex = /^[a-z][a-z0-9_]*$/
-        if name !~ name_regex
-          raise Bolt::ValidationError, <<~ERROR_STRING
-          Invalid project name '#{name}' in bolt-project.yaml; project name must match #{name_regex.inspect}
-          ERROR_STRING
+        if name !~ Bolt::Module::MODULE_NAME_REGEX
+          raise Bolt::ValidationError, "Invalid project name #{name.inspect.tr('"', "'")} in bolt-project.yaml; "\
+                                       "project name must match #{Bolt::Module::MODULE_NAME_REGEX.inspect}"
         elsif Dir.children(Bolt::PAL::BOLTLIB_PATH).include?(name)
           raise Bolt::ValidationError, "The project '#{name}' will not be loaded. The project name conflicts "\
             "with a built-in Bolt module of the same name."

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '2.21.0'
+  VERSION = '2.22.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 2.21.0
+  version: 2.22.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-03 00:00:00.000000000 Z
+date: 2020-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable