bolt 2.33.1 → 2.37.0

data/lib/bolt/config.rb

@@ -7,6 +7,7 @@ require 'bolt/project'
 require 'bolt/logger'
 require 'bolt/util'
 require 'bolt/config/options'
+require 'bolt/config/validator'
 
 module Bolt
   class UnknownTransportError < Bolt::Error
@@ -32,53 +33,97 @@ module Bolt
     end
 
     def self.from_project(project, overrides = {})
-      logs = []
+      logs         = []
+      deprecations = []
+
       conf = if project.project_file == project.config_file
                project.data
              else
                c = Bolt::Util.read_optional_yaml_hash(project.config_file, 'config')
+
+               # Validate the config against the schema. This will raise a single error
+               # with all validation errors.
+               Validator.new.tap do |validator|
+                 validator.validate(c, bolt_schema, project.config_file.to_s)
+
+                 validator.warnings.each { |warning| logs << { warn: warning } }
+
+                 validator.deprecations.each do |dep|
+                   deprecations << { type: "#{BOLT_CONFIG_NAME} #{dep[:option]}", msg: dep[:message] }
+                 end
+               end
+
                logs << { debug: "Loaded configuration from #{project.config_file}" } if File.exist?(project.config_file)
                c
              end
 
       data = load_defaults(project).push(
-        filepath: project.config_file,
-        data: conf,
-        logs: logs,
-        deprecations: []
+        filepath:     project.config_file,
+        data:         conf,
+        logs:         logs,
+        deprecations: deprecations
       )
 
       new(project, data, overrides)
     end
 
     def self.from_file(configfile, overrides = {})
-      project = Bolt::Project.create_project(Pathname.new(configfile).expand_path.dirname)
-      logs = []
+      project      = Bolt::Project.create_project(Pathname.new(configfile).expand_path.dirname)
+      logs         = []
+      deprecations = []
 
       conf = if project.project_file == project.config_file
                project.data
              else
                c = Bolt::Util.read_yaml_hash(configfile, 'config')
+
+               # Validate the config against the schema. This will raise a single error
+               # with all validation errors.
+               Validator.new.tap do |validator|
+                 validator.validate(c, bolt_schema, project.config_file.to_s)
+
+                 validator.warnings.each { |warning| logs << { warn: warning } }
+
+                 validator.deprecations.each do |dep|
+                   deprecations << { type: "#{BOLT_CONFIG_NAME} #{dep[:option]}", msg: dep[:message] }
+                 end
+               end
+
                logs << { debug: "Loaded configuration from #{configfile}" }
                c
              end
 
       data = load_defaults(project).push(
-        filepath: configfile,
-        data: conf,
-        logs: logs,
-        deprecations: []
+        filepath:     configfile,
+        data:         conf,
+        logs:         logs,
+        deprecations: deprecations
       )
 
       new(project, data, overrides)
     end
 
-    def self.system_path
-      # Lazy-load expensive gem code
-      require 'win32/dir' if Bolt::Util.windows?
+    def self.defaults_schema
+      base      = OPTIONS.slice(*BOLT_DEFAULTS_OPTIONS)
+      inventory = INVENTORY_OPTIONS.each_with_object({}) do |(option, definition), acc|
+        acc[option] = TRANSPORT_CONFIG.key?(option) ? definition.merge(TRANSPORT_CONFIG[option].schema) : definition
+      end
 
+      base['inventory-config'][:properties] = inventory
+      base
+    end
+
+    def self.bolt_schema
+      inventory = INVENTORY_OPTIONS.each_with_object({}) do |(option, definition), acc|
+        acc[option] = TRANSPORT_CONFIG.key?(option) ? definition.merge(TRANSPORT_CONFIG[option].schema) : definition
+      end
+
+      OPTIONS.slice(*BOLT_OPTIONS).merge(inventory)
+    end
+
+    def self.system_path
       if Bolt::Util.windows?
-        Pathname.new(File.join(Dir::COMMON_APPDATA, 'PuppetLabs', 'bolt', 'etc'))
+        Pathname.new(File.join(ENV['ALLUSERSPROFILE'], 'PuppetLabs', 'bolt', 'etc'))
       else
         Pathname.new(File.join('/etc', 'puppetlabs', 'bolt'))
       end
@@ -94,9 +139,10 @@ module Bolt
     # projects. This file does not allow project-specific configuration such as 'hiera-config' and
     # 'inventoryfile', and nests all default inventory configuration under an 'inventory-config' key.
     def self.load_bolt_defaults_yaml(dir)
-      filepath = dir + BOLT_DEFAULTS_NAME
-      data     = Bolt::Util.read_yaml_hash(filepath, 'config')
-      logs     = [{ debug: "Loaded configuration from #{filepath}" }]
+      filepath     = dir + BOLT_DEFAULTS_NAME
+      data         = Bolt::Util.read_yaml_hash(filepath, 'config')
+      logs         = [{ debug: "Loaded configuration from #{filepath}" }]
+      deprecations = []
 
       # Warn if 'bolt.yaml' detected in same directory.
       if File.exist?(bolt_yaml = dir + BOLT_CONFIG_NAME)
@@ -106,6 +152,18 @@ module Bolt
         )
       end
 
+      # Validate the config against the schema. This will raise a single error
+      # with all validation errors.
+      Validator.new.tap do |validator|
+        validator.validate(data, defaults_schema, filepath)
+
+        validator.warnings.each { |warning| logs << { warn: warning } }
+
+        validator.deprecations.each do |dep|
+          deprecations << { type: "#{BOLT_DEFAULTS_NAME} #{dep[:option]}", msg: dep[:message] }
+        end
+      end
+
       # Remove project-specific config such as hiera-config, etc.
       project_config = data.slice(*(BOLT_PROJECT_OPTIONS - BOLT_DEFAULTS_OPTIONS))
 
@@ -148,18 +206,30 @@ module Bolt
         data = data.merge(data.delete('inventory-config'))
       end
 
-      { filepath: filepath, data: data, logs: logs, deprecations: [] }
+      { filepath: filepath, data: data, logs: logs, deprecations: deprecations }
     end
 
     # Loads a 'bolt.yaml' file, the legacy configuration file. There's no special munging needed
     # here since Bolt::Config will just ignore any invalid keys.
     def self.load_bolt_yaml(dir)
-      filepath = dir + BOLT_CONFIG_NAME
-      data     = Bolt::Util.read_yaml_hash(filepath, 'config')
-      logs     = [{ debug: "Loaded configuration from #{filepath}" }]
+      filepath     = dir + BOLT_CONFIG_NAME
+      data         = Bolt::Util.read_yaml_hash(filepath, 'config')
+      logs         = [{ debug: "Loaded configuration from #{filepath}" }]
       deprecations = [{ type: 'Using bolt.yaml for system configuration',
-                        msg: "Configuration file #{filepath} is deprecated and will be removed in a future version "\
-                        "of Bolt. Use '#{dir + BOLT_DEFAULTS_NAME}' instead." }]
+                        msg: "Configuration file #{filepath} is deprecated and will be removed in Bolt 3.0. "\
+                        "See https://pup.pt/update-bolt-config for how to update to the latest Bolt practices." }]
+
+      # Validate the config against the schema. This will raise a single error
+      # with all validation errors.
+      Validator.new.tap do |validator|
+        validator.validate(data, bolt_schema, filepath)
+
+        validator.warnings.each { |warning| logs << { warn: warning } }
+
+        validator.deprecations.each do |dep|
+          deprecations << { type: "#{BOLT_CONFIG_NAME} #{dep[:option]}", msg: dep[:message] }
+        end
+      end
 
       { filepath: filepath, data: data, logs: logs, deprecations: deprecations }
     end
@@ -206,12 +276,14 @@ module Bolt
       @config_files = []
 
       default_data = {
+        'apply-settings'      => {},
         'apply_settings'      => {},
         'color'               => true,
         'compile-concurrency' => Etc.nprocessors,
         'concurrency'         => default_concurrency,
         'format'              => 'human',
         'log'                 => { 'console' => {} },
+        'plugin-hooks'        => {},
         'plugin_hooks'        => {},
         'plugins'             => {},
         'puppetdb'            => {},
@@ -271,7 +343,7 @@ module Bolt
 
       # Set console log to debug if in debug mode
       if options[:debug]
-        overrides['log'] = { 'console' => { 'level' => :debug } }
+        overrides['log'] = { 'console' => { 'level' => 'debug' } }
       end
 
       if options[:puppetfile_path]
@@ -280,6 +352,9 @@ module Bolt
 
       overrides['trace'] = opts['trace'] if opts.key?('trace')
 
+      # Validate the overrides
+      Validator.new.validate(overrides, OPTIONS, 'command line')
+
       overrides
     end
 
@@ -296,7 +371,7 @@ module Bolt
           when *TRANSPORT_CONFIG.keys
             Bolt::Util.deep_merge(val1, val2)
           # Hash values are shallow merged
-          when 'puppetdb', 'plugin_hooks', 'apply_settings', 'log'
+          when 'puppetdb', 'plugin-hooks', 'plugin_hooks', 'apply-settings', 'apply_settings', 'log'
             val1.merge(val2)
           # All other values are overwritten
           else
@@ -333,8 +408,9 @@ module Bolt
       end
 
       # Filter hashes to only include valid options
-      @data['apply_settings'] = @data['apply_settings'].slice(*OPTIONS['apply_settings'][:properties].keys)
-      @data['puppetfile'] = @data['puppetfile'].slice(*OPTIONS['puppetfile'][:properties].keys)
+      %w[apply-settings apply_settings puppetfile].each do |opt|
+        @data[opt] = @data[opt].slice(*OPTIONS.dig(opt, :properties).keys)
+      end
     end
 
     private def normalize_log(target)
@@ -372,10 +448,18 @@ module Bolt
             raise Bolt::ValidationError,
                   "level of log #{name} must be a String or Symbol, received #{v.class} #{v.inspect}"
           end
+
           unless Bolt::Logger.valid_level?(v)
             raise Bolt::ValidationError,
                   "level of log #{name} must be one of #{Bolt::Logger.levels.join(', ')}; received #{v}"
           end
+
+          if v == 'notice'
+            @deprecations << {
+              type: 'notice log level',
+              msg:  "Log level 'notice' is deprecated and will be removed in Bolt 3.0. Use 'info' instead."
+            }
+          end
         end
 
         if (v = acc[name][:append]) && v != true && v != false
@@ -397,37 +481,18 @@ module Bolt
               "is automatically appended to the modulepath and cannot be configured."
       end
 
-      keys = OPTIONS.keys - %w[plugins plugin_hooks puppetdb]
-      keys.each do |key|
-        next unless Bolt::Util.references?(@data[key])
-        valid_keys = TRANSPORT_CONFIG.keys + %w[plugins plugin_hooks puppetdb]
-        raise Bolt::ValidationError,
-              "Found unsupported key _plugin in config setting #{key}. Plugins are only available in "\
-              "#{valid_keys.join(', ')}."
-      end
-
-      unless concurrency.is_a?(Integer) && concurrency > 0
-        raise Bolt::ValidationError,
-              "Concurrency must be a positive Integer, received #{concurrency.class} #{concurrency}"
-      end
-
-      unless compile_concurrency.is_a?(Integer) && compile_concurrency > 0
-        raise Bolt::ValidationError,
-              "Compile concurrency must be a positive Integer, received #{compile_concurrency.class} "\
-              "#{compile_concurrency}"
-      end
-
       compile_limit = 2 * Etc.nprocessors
       unless compile_concurrency < compile_limit
         raise Bolt::ValidationError, "Compilation is CPU-intensive, set concurrency less than #{compile_limit}"
       end
 
-      unless %w[human json rainbow].include? format
-        raise Bolt::ValidationError, "Unsupported format: '#{format}'"
+      %w[hiera-config trusted-external-command inventoryfile].each do |opt|
+        Bolt::Util.validate_file(opt, @data[opt]) if @data[opt]
       end
 
-      Bolt::Util.validate_file('hiera-config', @data['hiera-config']) if @data['hiera-config']
-      Bolt::Util.validate_file('trusted-external-command', trusted_external) if trusted_external
+      if File.exist?(default_inventoryfile)
+        Bolt::Util.validate_file('inventory file', default_inventoryfile)
+      end
 
       unless TRANSPORT_CONFIG.include?(transport)
         raise UnknownTransportError, transport
@@ -464,6 +529,10 @@ module Bolt
       @data['modulepath'] = value
     end
 
+    def plugin_cache
+      @project.plugin_cache || @data['plugin-cache'] || {}
+    end
+
     def concurrency
       @data['concurrency']
     end
@@ -513,7 +582,18 @@ module Bolt
     end
 
     def plugin_hooks
-      @data['plugin_hooks']
+      if @data['plugin-hooks'].any? && @data['plugin_hooks'].any?
+        Bolt::Logger.warn_once(
+          "plugin-hooks and plugin_hooks set",
+          "Detected configuration for 'plugin-hooks' and 'plugin_hooks'. Bolt will ignore 'plugin_hooks'."
+        )
+
+        @data['plugin-hooks']
+      elsif @data['plugin-hooks'].any?
+        @data['plugin-hooks']
+      else
+        @data['plugin_hooks']
+      end
     end
 
     def trusted_external
@@ -521,7 +601,18 @@ module Bolt
     end
 
     def apply_settings
-      @data['apply_settings']
+      if @data['apply-settings'].any? && @data['apply_settings'].any?
+        Bolt::Logger.warn_once(
+          "apply-settings and apply_settings set",
+          "Detected configuration for 'apply-settings' and 'apply_settings'. Bolt will ignore 'apply_settings'."
+        )
+
+        @data['apply-settings']
+      elsif @data['apply-settings'].any?
+        @data['apply-settings']
+      else
+        @data['apply_settings']
+      end
     end
 
     def transport

data/lib/bolt/config/options.rb

@@ -33,6 +33,18 @@ module Bolt
             "_plugin" => {
               description: "The name of the plugin.",
               type: "string"
+            },
+            "_cache" => {
+              description: "This feature is experimental. Enable plugin caching and set a time-to-live.",
+              type: "object",
+              required: ["ttl"],
+              properties: {
+                "ttl" => {
+                  description: "Time in seconds to keep the plugin cache.",
+                  type: "integer",
+                  minimum: 0
+                }
+              }
             }
           }
         }
@@ -104,6 +116,21 @@ module Bolt
       #                               files and is not used by Bolt to actually set default values.
       OPTIONS = {
         "apply_settings" => {
+          description: "A map of Puppet settings to use when applying Puppet code using the `apply` "\
+                       "plan function or the `bolt apply` command.",
+          type: Hash,
+          properties: {
+            "show_diff" => {
+              description: "Whether to log and report a contextual diff.",
+              type: [TrueClass, FalseClass],
+              _example: true,
+              _default: false
+            }
+          },
+          _plugin: false,
+          _deprecation: "This option will be removed in Bolt 3.0. Use `apply-settings` instead."
+        },
+        "apply-settings" => {
           description: "A map of Puppet settings to use when applying Puppet code using the `apply` "\
                        "plan function or the `bolt apply` command.",
           type: Hash,
@@ -169,9 +196,26 @@ module Bolt
                        "files](inventory_file_v2.md).",
           type: String,
           _plugin: false,
+          _deprecation: "This option will be removed in Bolt 3.0. Use the `--inventoryfile` command-line option "\
+                        "to use a non-default inventory file or move the file contents to `inventory.yaml` in the "\
+                        "project directory.",
           _example: "~/.puppetlabs/bolt/inventory.yaml",
           _default: "project/inventory.yaml"
         },
+        "plugin-cache" => {
+          description: "This feature is experimental. Enable plugin caching and set the time-to-live.",
+          type: Hash,
+          required: ["ttl"],
+          properties: {
+            "ttl" => {
+              description: "Time in seconds to keep the plugin cache.",
+              type: Integer,
+              minimum: 0
+            }
+          },
+          _plugin: false,
+          _example: { "ttl" => 3600 }
+        },
         "log" => {
           description: "A map of configuration for the logfile output. Under `log`, you can configure log options "\
                        "for `console` and add configuration for individual log files, such as "\
@@ -183,12 +227,13 @@ module Bolt
           properties: {
             "console" => {
               description: "Configuration for logs output to the console.",
-              type: Hash,
+              type: [String, Hash],
+              enum: ['disable'],
               properties: {
                 "level" => {
                   description: "The type of information to log.",
                   type: String,
-                  enum: %w[trace debug error info warn fatal any],
+                  enum: %w[trace debug error info notice warn fatal any],
                   _default: "warn"
                 }
               }
@@ -207,7 +252,7 @@ module Bolt
               "level" => {
                 description: "The type of information to log.",
                 type: String,
-                enum: %w[trace debug error info warn fatal any],
+                enum: %w[trace debug error info notice warn fatal any],
                 _default: "warn"
               }
             }
@@ -276,14 +321,14 @@ module Bolt
         },
         "name" => {
           description: "The name of the Bolt project. When this option is configured, the project is considered a "\
-                       "[Bolt project](experimental_features.md#bolt-projects), allowing Bolt to load content from "\
-                       "the project directory as though it were a module.",
+                       "[Bolt project](projects.md), allowing Bolt to load content from the project directory "\
+                       "as though it were a module.",
           type: String,
           _plugin: false,
           _example: "myproject"
         },
         "plans" => {
-          description: "A list of plan names to show in `bolt plan show` output, if they exist. This option is used "\
+          description: "A list of plan names and glob patterns to filter the project's plans by. This option is used "\
                        "to limit the visibility of plans for users of the project. For example, project authors "\
                        "might want to limit the visibility of plans that are bundled with Bolt or plans that should "\
                        "only be run as part of another plan. When this option is not configured, all plans are "\
@@ -291,9 +336,19 @@ module Bolt
                        "list.",
           type: Array,
           _plugin: false,
-          _example: ["myproject", "myproject::foo", "myproject::bar"]
+          _example: ["myproject", "myproject::foo", "myproject::bar", "myproject::deploy::*"]
         },
         "plugin_hooks" => {
+          description: "A map of [plugin hooks](writing_plugins.md#hooks) and which plugins a hook should use. "\
+                       "The only configurable plugin hook is `puppet_library`, which can use two possible plugins: "\
+                       "[`puppet_agent`](https://github.com/puppetlabs/puppetlabs-puppet_agent#puppet_agentinstall) "\
+                       "and [`task`](using_plugins.md#task).",
+          type: Hash,
+          _plugin: true,
+          _example: { "puppet_library" => { "plugin" => "puppet_agent", "version" => "6.15.0", "_run_as" => "root" } },
+          _deprecation: "This option will be removed in Bolt 3.0. Use `plugin-hooks` instead."
+        },
+        "plugin-hooks" => {
           description: "A map of [plugin hooks](writing_plugins.md#hooks) and which plugins a hook should use. "\
                        "The only configurable plugin hook is `puppet_library`, which can use two possible plugins: "\
                        "[`puppet_agent`](https://github.com/puppetlabs/puppetlabs-puppet_agent#puppet_agentinstall) "\
@@ -307,7 +362,11 @@ module Bolt
                        "its value is a map of configuration data. Configurable options are specified by the plugin. "\
                        "Read more about configuring plugins in [Using plugins](using_plugins.md#configuring-plugins).",
           type: Hash,
-          _plugin: true,
+          additionalProperties: {
+            type: Hash,
+            _plugin: true
+          },
+          _plugin: false,
           _example: { "pkcs7" => { "keysize" => 1024 } }
         },
         "puppetdb" => {
@@ -402,7 +461,7 @@ module Bolt
           _default: true
         },
         "tasks" => {
-          description: "A list of task names to show in `bolt task show` output, if they exist. This option is used "\
+          description: "A list of task names and glob patterns to filter the project's tasks by. This option is used "\
                        "to limit the visibility of tasks for users of the project. For example, project authors "\
                        "might want to limit the visibility of tasks that are bundled with Bolt or plans that should "\
                        "only be run as part of a larger workflow. When this option is not configured, all tasks "\
@@ -413,7 +472,7 @@ module Bolt
             type: String
           },
           _plugin: false,
-          _example: ["myproject", "myproject::foo", "myproject::bar"]
+          _example: ["myproject", "myproject::foo", "myproject::bar", "myproject::deploy_*"]
         },
         "trusted-external-command" => {
           description: "The path to an executable on the Bolt controller that can produce external trusted facts. "\
@@ -480,6 +539,7 @@ module Bolt
 
       # Options that are available in a bolt.yaml file
       BOLT_OPTIONS = %w[
+        apply-settings
         apply_settings
         color
         compile-concurrency
@@ -489,6 +549,7 @@ module Bolt
         inventoryfile
         log
         modulepath
+        plugin-hooks
         plugin_hooks
         plugins
         puppetdb
@@ -505,6 +566,8 @@ module Bolt
         format
         inventory-config
         log
+        plugin-cache
+        plugin-hooks
         plugin_hooks
         plugins
         puppetdb
@@ -514,6 +577,7 @@ module Bolt
 
       # Options that are available in a bolt-project.yaml file
       BOLT_PROJECT_OPTIONS = %w[
+        apply-settings
         apply_settings
         color
         compile-concurrency
@@ -526,6 +590,8 @@ module Bolt
         modules
         name
         plans
+        plugin-cache
+        plugin-hooks
         plugin_hooks
         plugins
         puppetdb