bolt 2.14.0 → 2.19.0

data/lib/bolt/config.rb

@@ -6,13 +6,7 @@ require 'pathname'
 require 'bolt/project'
 require 'bolt/logger'
 require 'bolt/util'
-# Transport config objects
-require 'bolt/config/transport/ssh'
-require 'bolt/config/transport/winrm'
-require 'bolt/config/transport/orch'
-require 'bolt/config/transport/local'
-require 'bolt/config/transport/docker'
-require 'bolt/config/transport/remote'
+require 'bolt/config/options'
 
 module Bolt
   class UnknownTransportError < Bolt::Error
@@ -23,95 +17,18 @@ module Bolt
   end
 
   class Config
-    attr_reader :config_files, :warnings, :data, :transports, :project, :modified_concurrency
-
-    TRANSPORT_CONFIG = {
-      'ssh'    => Bolt::Config::Transport::SSH,
-      'winrm'  => Bolt::Config::Transport::WinRM,
-      'pcp'    => Bolt::Config::Transport::Orch,
-      'local'  => Bolt::Config::Transport::Local,
-      'docker' => Bolt::Config::Transport::Docker,
-      'remote' => Bolt::Config::Transport::Remote
-    }.freeze
-
-    TRANSPORT_OPTION = { 'transport' => 'The default transport to use when the '\
-                         'transport for a target is not specified in the URL.' }.freeze
-
-    DEFAULT_TRANSPORT_OPTION = { 'transport' => 'ssh' }.freeze
-
-    CONFIG_IN_INVENTORY = TRANSPORT_CONFIG.merge(TRANSPORT_OPTION)
-
-    # NOTE: All configuration options should have a corresponding schema property
-    #       in schemas/bolt-config.schema.json
-    OPTIONS = {
-      "apply_settings"           => "A map of Puppet settings to use when applying Puppet code",
-      "color"                    => "Whether to use colored output when printing messages to the console.",
-      "compile-concurrency"      => "The maximum number of simultaneous manifest block compiles.",
-      "concurrency"              => "The number of threads to use when executing on remote targets.",
-      "format"                   => "The format to use when printing results. Options are `human` and `json`.",
-      "hiera-config"             => "The path to your Hiera config.",
-      "inventoryfile"            => "The path to a structured data inventory file used to refer to groups of "\
-                                    "targets on the command line and from plans.",
-      "log"                      => "The configuration of the logfile output. Configuration can be set for "\
-                                    "`console` and the path to a log file, such as `~/.puppetlabs/bolt/debug.log`.",
-      "modulepath"               => "An array of directories that Bolt loads content (e.g. plans and tasks) from.",
-      "plugin_hooks"             => "Which plugins a specific hook should use.",
-      "plugins"                  => "A map of plugins and their configuration data.",
-      "puppetdb"                 => "A map containing options for configuring the Bolt PuppetDB client.",
-      "puppetfile"               => "A map containing options for the `bolt puppetfile install` command.",
-      "save-rerun"               => "Whether to update `.rerun.json` in the Bolt project directory. If "\
-                                    "your target names include passwords, set this value to `false` to avoid "\
-                                    "writing passwords to disk.",
-      "transport"                => "The default transport to use when the transport for a target is not specified "\
-                                    "in the URL or inventory.",
-      "trusted-external-command" => "The path to an executable on the Bolt controller that can produce "\
-                                    "external trusted facts. **External trusted facts are experimental in both "\
-                                    "Puppet and Bolt and this API may change or be removed.**"
-    }.freeze
-
-    DEFAULT_OPTIONS = {
-      "color" => true,
-      "compile-concurrency" => "Number of cores",
-      "concurrency" => "100 or one-third of the ulimit, whichever is lower",
-      "format" => "human",
-      "hiera-config" => "Boltdir/hiera.yaml",
-      "inventoryfile" => "Boltdir/inventory.yaml",
-      "modulepath" => ["Boltdir/modules", "Boltdir/site-modules", "Boltdir/site"],
-      "save-rerun" => true
-    }.freeze
-
-    PUPPETFILE_OPTIONS = {
-      "forge" => "A subsection that can have its own `proxy` setting to set an HTTP proxy for Forge operations "\
-                 "only, and a `baseurl` setting to specify a different Forge host.",
-      "proxy" => "The HTTP proxy to use for Git and Forge operations."
-    }.freeze
-
-    LOG_OPTIONS = {
-      "append" => "Add output to an existing log file. Available only for logs output to a "\
-                  "filepath.",
-      "level"  => "The type of information in the log. Either `debug`, `info`, `notice`, "\
-                  "`warn`, or `error`."
-    }.freeze
-
-    DEFAULT_LOG_OPTIONS = {
-      "append" => true,
-      "level"  => "`warn` for console, `notice` for file"
-    }.freeze
-
-    APPLY_SETTINGS = {
-      "show_diff" => "Whether to log and report a contextual diff when files are being replaced. "\
-                     "See [Puppet documentation](https://puppet.com/docs/puppet/latest/configuration.html#showdiff) "\
-                     "for details"
-    }.freeze
-
-    DEFAULT_APPLY_SETTINGS = {
-      "show_diff" => false
-    }.freeze
+    include Bolt::Config::Options
 
+    attr_reader :config_files, :warnings, :data, :transports, :project, :modified_concurrency, :deprecations
+
+    BOLT_CONFIG_NAME = 'bolt.yaml'
+    BOLT_DEFAULTS_NAME = 'bolt-defaults.yaml'
+
+    # The default concurrency value that is used when the ulimit is not low (i.e. < 700)
     DEFAULT_DEFAULT_CONCURRENCY = 100
 
     def self.default
-      new(Bolt::Project.create_project('.'), {})
+      new(Bolt::Project.default_project, {})
     end
 
     def self.from_project(project, overrides = {})
@@ -121,57 +38,164 @@ module Bolt
                Bolt::Util.read_optional_yaml_hash(project.config_file, 'config')
              end
 
-      data = { filepath: project.config_file, data: conf }
-
-      data = load_defaults(project).push(data).select { |config| config[:data]&.any? }
+      data = load_defaults(project).push(
+        filepath: project.config_file,
+        data: conf,
+        warnings: [],
+        deprecations: []
+      )
 
       new(project, data, overrides)
     end
 
     def self.from_file(configfile, overrides = {})
       project = Bolt::Project.create_project(Pathname.new(configfile).expand_path.dirname)
+
       conf = if project.project_file == project.config_file
                project.data
              else
                Bolt::Util.read_yaml_hash(configfile, 'config')
              end
-      data = { filepath: project.config_file, data: conf }
-      data = load_defaults(project).push(data).select { |config| config[:data]&.any? }
+
+      data = load_defaults(project).push(
+        filepath: project.config_file,
+        data: conf,
+        warnings: [],
+        deprecations: []
+      )
 
       new(project, data, overrides)
     end
 
-    def self.load_defaults(project)
+    def self.system_path
       # Lazy-load expensive gem code
       require 'win32/dir' if Bolt::Util.windows?
 
-      # Don't load /etc/puppetlabs/bolt/bolt.yaml twice
-      confs = if project.path == Bolt::Project.system_path
-                []
-              else
-                system_path = Pathname.new(File.join(Bolt::Project.system_path, 'bolt.yaml'))
-                [{ filepath: system_path, data: Bolt::Util.read_optional_yaml_hash(system_path, 'config') }]
-              end
-
-      user_path = begin
-                    Pathname.new(File.expand_path(File.join('~', '.puppetlabs', 'etc', 'bolt', 'bolt.yaml')))
-                  rescue ArgumentError
-                    nil
-                  end
-
-      confs << { filepath: user_path, data: Bolt::Util.read_optional_yaml_hash(user_path, 'config') } if user_path
+      if Bolt::Util.windows?
+        Pathname.new(File.join(Dir::COMMON_APPDATA, 'PuppetLabs', 'bolt', 'etc'))
+      else
+        Pathname.new(File.join('/etc', 'puppetlabs', 'bolt'))
+      end
+    end
+
+    def self.user_path
+      Pathname.new(File.expand_path(File.join('~', '.puppetlabs', 'etc', 'bolt')))
+    rescue StandardError
+      nil
+    end
+
+    # Loads a 'bolt-defaults.yaml' file, which contains default configuration that applies to all
+    # 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')
+      warnings = []
+
+      # Warn if 'bolt.yaml' detected in same directory.
+      if File.exist?(bolt_yaml = dir + BOLT_CONFIG_NAME)
+        warnings.push(
+          msg: "Detected multiple configuration files: ['#{bolt_yaml}', '#{filepath}']. '#{bolt_yaml}' "\
+               "will be ignored."
+        )
+      end
+
+      # Remove project-specific config such as hiera-config, etc.
+      project_config = data.slice(*(BOLT_PROJECT_OPTIONS - BOLT_DEFAULTS_OPTIONS))
+
+      if project_config.any?
+        data.reject! { |key, _| project_config.include?(key) }
+        warnings.push(
+          msg: "Unsupported project configuration detected in '#{filepath}': #{project_config.keys}. "\
+                "Project configuration should be set in 'bolt-project.yaml'."
+        )
+      end
+
+      # Remove top-level transport config such as transport, ssh, etc.
+      transport_config = data.slice(*INVENTORY_OPTIONS.keys)
+
+      if transport_config.any?
+        data.reject! { |key, _| transport_config.include?(key) }
+        warnings.push(
+          msg: "Unsupported inventory configuration detected in '#{filepath}': #{transport_config.keys}. "\
+               "Transport configuration should be set under the 'inventory-config' option or "\
+               "in 'inventory.yaml'."
+        )
+      end
+
+      # Move data under inventory-config to top-level so it can be easily merged with
+      # config from other sources. Error early if inventory-config is not a hash or
+      # has a plugin reference.
+      if data.key?('inventory-config')
+        unless data['inventory-config'].is_a?(Hash)
+          raise Bolt::ValidationError,
+                "Option 'inventory-config' must be of type Hash, received #{data['inventory-config']} "\
+                "#{data['inventory-config']} (file: #{filepath})"
+        end
+
+        if data['inventory-config'].key?('_plugin')
+          raise Bolt::ValidationError,
+                "Found unsupported key '_plugin' for option 'inventory-config'; supported keys are "\
+                "'#{INVENTORY_OPTIONS.keys.join("', '")}' (file: #{filepath})"
+        end
+
+        data = data.merge(data.delete('inventory-config'))
+      end
+
+      { filepath: filepath, data: data, warnings: warnings, 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')
+      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." }]
+
+      { filepath: filepath, data: data, warnings: [], deprecations: deprecations }
+    end
+
+    def self.load_defaults(project)
+      confs = []
+
+      # Load system-level config. Prefer a 'bolt-defaults.yaml' file, but fall back to the
+      # legacy 'bolt.yaml' file. If the project-level config file is also the system-level
+      # config file, don't load it a second time.
+      if File.exist?(system_path + BOLT_DEFAULTS_NAME)
+        confs << load_bolt_defaults_yaml(system_path)
+      elsif File.exist?(system_path + BOLT_CONFIG_NAME) &&
+            (system_path + BOLT_CONFIG_NAME) != project.config_file
+        confs << load_bolt_yaml(system_path)
+      end
+
+      # Load user-level config if there is a homedir. Prefer a 'bolt-defaults.yaml' file, but
+      # fall back to the legacy 'bolt.yaml' file.
+      if user_path
+        if File.exist?(user_path + BOLT_DEFAULTS_NAME)
+          confs << load_bolt_defaults_yaml(user_path)
+        elsif File.exist?(user_path + BOLT_CONFIG_NAME)
+          confs << load_bolt_yaml(user_path)
+        end
+      end
+
       confs
     end
 
     def initialize(project, config_data, overrides = {})
       unless config_data.is_a?(Array)
-        config_data = [{ filepath: project.config_file, data: config_data }]
+        config_data = [{ filepath: project.config_file,
+                         data: config_data,
+                         warnings: [],
+                         deprecations: [] }]
       end
 
-      @logger = Logging.logger[self]
-      @project = project
-      @warnings = @project.warnings.dup
-      @transports = {}
+      @logger       = Logging.logger[self]
+      @project      = project
+      @warnings     = @project.warnings.dup
+      @deprecations = @project.deprecations.dup
+      @transports   = {}
       @config_files = []
 
       default_data = {
@@ -189,9 +213,14 @@ module Bolt
         'transport'           => 'ssh'
       }
 
-      loaded_data = config_data.map do |config|
-        @config_files.push(config[:filepath])
-        config[:data]
+      loaded_data = config_data.each_with_object([]) do |data, acc|
+        @warnings.concat(data[:warnings]) if data[:warnings].any?
+        @deprecations.concat(data[:deprecations]) if data[:deprecations].any?
+
+        if data[:data].any?
+          @config_files.push(data[:filepath])
+          acc.push(data[:data])
+        end
       end
 
       override_data = normalize_overrides(overrides)
@@ -217,12 +246,13 @@ module Bolt
     def normalize_overrides(options)
       opts = options.transform_keys(&:to_s)
 
-      # Pull out config options
-      overrides = opts.slice(*OPTIONS.keys)
+      # Pull out config options. We need to add 'transport' as it's not part of the
+      # OPTIONS hash but is a valid option that can be set with the --transport CLI option
+      overrides = opts.slice(*OPTIONS.keys, 'transport')
 
       # Pull out transport config options
       TRANSPORT_CONFIG.each do |transport, config|
-        overrides[transport] = opts.slice(*config.options.keys)
+        overrides[transport] = opts.slice(*config.options)
       end
 
       # Set console log to debug if in debug mode
@@ -289,8 +319,8 @@ module Bolt
       end
 
       # Filter hashes to only include valid options
-      @data['apply_settings'] = @data['apply_settings'].slice(*APPLY_SETTINGS.keys)
-      @data['puppetfile'] = @data['puppetfile'].slice(*PUPPETFILE_OPTIONS.keys)
+      @data['apply_settings'] = @data['apply_settings'].slice(*OPTIONS['apply_settings'][:properties].keys)
+      @data['puppetfile'] = @data['puppetfile'].slice(*OPTIONS['puppetfile'][:properties].keys)
     end
 
     private def normalize_log(target)
@@ -304,7 +334,7 @@ module Bolt
         next unless val.is_a?(Hash)
 
         name = normalize_log(key)
-        acc[name] = val.slice(*LOG_OPTIONS.keys)
+        acc[name] = val.slice('append', 'level')
                        .transform_keys(&:to_sym)
 
         if (v = acc[name][:level])
@@ -356,7 +386,7 @@ module Bolt
         raise Bolt::ValidationError, "Compilation is CPU-intensive, set concurrency less than #{compile_limit}"
       end
 
-      unless %w[human json].include? format
+      unless %w[human json rainbow].include? format
         raise Bolt::ValidationError, "Unsupported format: '#{format}'"
       end
 

data/lib/bolt/config/options.rb

@@ -0,0 +1,474 @@
+# frozen_string_literal: true
+
+require 'bolt/config/transport/ssh'
+require 'bolt/config/transport/winrm'
+require 'bolt/config/transport/orch'
+require 'bolt/config/transport/local'
+require 'bolt/config/transport/docker'
+require 'bolt/config/transport/remote'
+
+module Bolt
+  class Config
+    module Options
+      # Transport config classes. Used to load default transport config which
+      # gets passed along to the inventory.
+      TRANSPORT_CONFIG = {
+        'ssh'    => Bolt::Config::Transport::SSH,
+        'winrm'  => Bolt::Config::Transport::WinRM,
+        'pcp'    => Bolt::Config::Transport::Orch,
+        'local'  => Bolt::Config::Transport::Local,
+        'docker' => Bolt::Config::Transport::Docker,
+        'remote' => Bolt::Config::Transport::Remote
+      }.freeze
+
+      # Plugin definition. This is used by the JSON schemas to indicate that an option
+      # accepts a plugin reference. Since this isn't used by Bolt to perform automatic
+      # type validation, the :type key is set to a JSON type instead of a Ruby type.
+      PLUGIN = {
+        "_plugin" => {
+          description: "A plugin reference.",
+          type: "object",
+          required: ["_plugin"],
+          properties: {
+            "_plugin" => {
+              description: "The name of the plugin.",
+              type: "string"
+            }
+          }
+        }
+      }.freeze
+
+      # The following constants define the various configuration options available to Bolt.
+      # Each constant is a hash where keys are the configuration option and values are the
+      # option's definition. These options are used in multiple locations:
+      #
+      #   - Automatic type validation when loading and setting configuration
+      #   - Generating reference documentation for configuration files
+      #   - Generating JSON schemas for configuration files
+      #
+      # Data includes keys defined by JSON Schema Draft 07 as well as some metadata used
+      # by Bolt to generate documentation. The following keys are used:
+      #
+      #   :description    String      A detailed description of the option and what it does. This
+      #                               field is used in both documentation and the JSON schemas,
+      #                               and should provide as much detail as possible, including
+      #                               links to relevant documentation.
+      #
+      #   :type           Class       The expected type of a value. These should be Ruby classes,
+      #                               as this field is used to perform automatic type validation.
+      #                               If an option can accept more than one type, this should be
+      #                               an array of types. Boolean values should set :type to
+      #                               [TrueClass, FalseClass], as Ruby does not have a single
+      #                               Boolean class.
+      #
+      #   :items          Hash        A definition hash for items in an array. Similar to values
+      #                               for top-level options, items can have a :description, :type,
+      #                               or any other key in this list.
+      #
+      #   :uniqueItems    Boolean     Whether or not an array should contain only unique items.
+      #
+      #   :properties     Hash        A hash where keys are sub-options and values are definitions
+      #                               for the sub-option. Similar to values for top-level options,
+      #                               properties can have a :description, :type, or any other key
+      #                               in this list.
+      #
+      #   :additionalProperties       A variation of the :properties key, where the hash is a
+      #                   Hash        definition for any properties not specified in :properties.
+      #                               This can be used to permit arbitrary sub-options, such as
+      #                               logs for the 'log' option.
+      #
+      #   :required       Array       An array of properties that are required for options that
+      #                               accept Hash values.
+      #
+      #   :minimum        Integer     The minimum integer value for an option.
+      #
+      #   :enum           Array       An array of values that the option recognizes.
+      #
+      #   :pattern        String      A JSON regex pattern that the option's vaue should match.
+      #
+      #   :format         String      Requires that a string value matches a format defined by the
+      #                               JSON Schema draft.
+      #
+      #   :_plugin        Boolean     Whether the option accepts a plugin reference. This is used
+      #                               when generating the JSON schemas to determine whether or not
+      #                               to include a reference to the _plugin definition. If :_plugin
+      #                               is set to true, the script that generates JSON schemas will
+      #                               automatically recurse through the :items and :properties keys
+      #                               and add plugin references if applicable.
+      #
+      #   :_example       Any         An example value for the option. This is used to generate
+      #                               reference documentation for configuration files.
+      #
+      #   :_default       Any         The documented default value for the option. This is only
+      #                               used to generate reference documentation for configuration
+      #                               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
+        },
+        "color" => {
+          description: "Whether to use colored output when printing messages to the console.",
+          type: [TrueClass, FalseClass],
+          _plugin: false,
+          _example: false,
+          _default: true
+        },
+        "compile-concurrency" => {
+          description: "The maximum number of simultaneous manifest block compiles.",
+          type: Integer,
+          minimum: 1,
+          _plugin: false,
+          _example: 5,
+          _default: "Number of cores."
+        },
+        "concurrency" => {
+          description: "The number of threads to use when executing on remote targets.",
+          type: Integer,
+          minimum: 1,
+          _plugin: false,
+          _example: 50,
+          _default: "100 or 1/7 the ulimit, whichever is lower."
+        },
+        "format" => {
+          description: "The format to use when printing results.",
+          type: String,
+          enum: %w[human json rainbow],
+          _plugin: false,
+          _example: "json",
+          _default: "human"
+        },
+        "hiera-config" => {
+          description: "The path to the Hiera configuration file.",
+          type: String,
+          _plugin: false,
+          _example: "~/.puppetlabs/bolt/hiera.yaml",
+          _default: "project/hiera.yaml"
+        },
+        "inventory-config" => {
+          description: "A map of default configuration options for the inventory. This includes options "\
+                       "for setting the default transport to use when connecting to targets, as well as "\
+                       "options for configuring the default behavior of each transport.",
+          type: Hash,
+          _plugin: false,
+          _example: {}
+        },
+        "inventoryfile" => {
+          description: "The path to a structured data inventory file used to refer to groups of targets on the "\
+                       "command line and from plans. Read more about using inventory files in [Inventory "\
+                       "files](inventory_file_v2.md).",
+          type: String,
+          _plugin: false,
+          _example: "~/.puppetlabs/bolt/inventory.yaml",
+          _default: "project/inventory.yaml"
+        },
+        "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 "\
+                       "`~/.puppetlabs/bolt/debug.log`. Individual log files must be valid filepaths. If the log "\
+                       "file does not exist, then Bolt will create it before logging information.",
+          type: Hash,
+          properties: {
+            "console" => {
+              description: "Configuration for logs output to the console.",
+              type: Hash,
+              properties: {
+                "level" => {
+                  description: "The type of information to log.",
+                  type: String,
+                  enum: %w[debug error info notice warn fatal any],
+                  _default: "warn for console, notice for file"
+                }
+              }
+            }
+          },
+          additionalProperties: {
+            description: "Configuration for the logfile output.",
+            type: Hash,
+            properties: {
+              "append" => {
+                description: "Whether to append output to an existing log file.",
+                type: [TrueClass, FalseClass],
+                _default: true
+              },
+              "level" => {
+                description: "The type of information to log.",
+                type: String,
+                enum: %w[debug error info notice warn fatal any],
+                _default: "warn for console, notice for file"
+              }
+            }
+          },
+          _plugin: false,
+          _example: { "console" => { "level" => "info" },
+                      "~/logs/debug.log" => { "append" => false, "level" => "debug" } }
+        },
+        "modulepath" => {
+          description: "An array of directories that Bolt loads content such as plans and tasks from. Read more "\
+                       "about modules in [Module structure](module_structure.md).",
+          type: [Array, String],
+          items: {
+            type: String
+          },
+          _plugin: false,
+          _example: ["~/.puppetlabs/bolt/modules", "~/.puppetlabs/bolt/site-modules"],
+          _default: ["project/modules", "project/site-modules", "project/site"]
+        },
+        "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.",
+          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 "\
+                       "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 "\
+                       "visible. This option does not prevent users from running plans that are not part of this "\
+                       "list.",
+          type: Array,
+          _plugin: false,
+          _example: ["myproject", "myproject::foo", "myproject::bar"]
+        },
+        "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" } }
+        },
+        "plugins" => {
+          description: "A map of plugins and their configuration data, where each key is the name of a plugin and "\
+                       "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,
+          _example: { "pkcs7" => { "keysize" => 1024 } }
+        },
+        "puppetdb" => {
+          description: "A map containing options for [configuring the Bolt PuppetDB "\
+                       "client](bolt_connect_puppetdb.md).",
+          type: Hash,
+          properties: {
+            "cacert" => {
+              description: "The path to the ca certificate for PuppetDB.",
+              type: String,
+              _example: "/etc/puppetlabs/puppet/ssl/certs/ca.pem"
+            },
+            "cert" => {
+              description: "The path to the client certificate file to use for authentication.",
+              type: String,
+              _example: "/etc/puppetlabs/puppet/ssl/certs/my-host.example.com.pem"
+            },
+            "key" => {
+              description: "The private key for the certificate.",
+              type: String,
+              _example: "/etc/puppetlabs/puppet/ssl/private_keys/my-host.example.com.pem"
+            },
+            "server_urls" => {
+              description: "An array containing the PuppetDB host to connect to. Include the protocol `https` "\
+                           "and the port, which is usually `8081`. For example, "\
+                           "`https://my-master.example.com:8081`.",
+              type: Array,
+              _example: ["https://puppet.example.com:8081"]
+            },
+            "token" => {
+              description: "The path to the PE RBAC Token.",
+              type: String,
+              _example: "~/.puppetlabs/token"
+            }
+          },
+          _plugin: true
+        },
+        "puppetfile" => {
+          description: "A map containing options for the `bolt puppetfile install` command.",
+          type: Hash,
+          properties: {
+            "forge" => {
+              description: "A subsection that can have its own `proxy` setting to set an HTTP proxy for Forge "\
+                           "operations only, and a `baseurl` setting to specify a different Forge host.",
+              type: Hash,
+              properties: {
+                "baseurl" => {
+                  description: "The URL to the Forge host.",
+                  type: String,
+                  format: "uri",
+                  _example: "https://forge.example.com"
+                },
+                "proxy" => {
+                  description: "The HTTP proxy to use for Git and Forge operations.",
+                  type: String,
+                  format: "uri",
+                  _example: "https://forgeapi.example.com"
+                }
+              },
+              _example: { "baseurl" => "https://forge.example.com", "proxy" => "https://forgeapi.example.com" }
+            },
+            "proxy" => {
+              description: "The HTTP proxy to use for Git and Forge operations.",
+              type: String,
+              format: "uri",
+              _example: "https://forgeapi.example.com"
+            }
+          },
+          _plugin: false
+        },
+        "save-rerun" => {
+          description: "Whether to update `.rerun.json` in the Bolt project directory. If "\
+                       "your target names include passwords, set this value to `false` to avoid "\
+                       "writing passwords to disk.",
+          type: [TrueClass, FalseClass],
+          _plugin: false,
+          _example: false,
+          _default: true
+        },
+        "tasks" => {
+          description: "A list of task names to show in `bolt task show` output, if they exist. 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 "\
+                       "are visible. This option does not prevent users from running tasks that are not part of "\
+                       "this list.",
+          type: Array,
+          items: {
+            type: String
+          },
+          _plugin: false,
+          _example: ["myproject", "myproject::foo", "myproject::bar"]
+        },
+        "trusted-external-command" => {
+          description: "The path to an executable on the Bolt controller that can produce external trusted facts. "\
+                       "**External trusted facts are experimental in both Puppet and Bolt and this API may change or "\
+                       "be removed.**",
+          type: String,
+          _plugin: false,
+          _example: "/etc/puppetlabs/facts/trusted_external.sh"
+        }
+      }.freeze
+
+      # Options that configure the inventory, specifically the default transport
+      # used by targets and the transports themselves. These options are used in
+      # bolt.yaml, under a 'config' key in inventory.yaml, and under the
+      # 'inventory-config' key in bolt-defaults.yaml.
+      INVENTORY_OPTIONS = {
+        "transport" => {
+          description: "The default transport to use when the transport for a target is not "\
+                       "specified in the URI.",
+          type: String,
+          enum: TRANSPORT_CONFIG.keys,
+          _plugin: false,
+          _example: "winrm",
+          _default: "ssh"
+        },
+        "docker" => {
+          description: "A map of configuration options for the docker transport.",
+          type: Hash,
+          _plugin: true,
+          _example: { "cleanup" => false, "service-url" => "https://docker.example.com" }
+        },
+        "local" => {
+          description: "A map of configuration options for the local transport. The set of available options is "\
+                       "platform dependent.",
+          type: Hash,
+          _plugin: true,
+          _example: { "cleanup" => false, "tmpdir" => "/tmp/bolt" }
+        },
+        "pcp" => {
+          description: "A map of configuration options for the pcp transport.",
+          type: Hash,
+          _plugin: true,
+          _example: { "job-poll-interval" => 15, "job-poll-timeout" => 30 }
+        },
+        "remote" => {
+          description: "A map of configuration options for the remote transport.",
+          type: Hash,
+          _plugin: true,
+          _example: { "run-on" => "proxy_target" }
+        },
+        "ssh" => {
+          description: "A map of configuration options for the ssh transport.",
+          type: Hash,
+          _plugin: true,
+          _example: { "password" => "hunter2!", "user" => "bolt" }
+        },
+        "winrm" => {
+          description: "A map of configuration options for the winrm transport.",
+          type: Hash,
+          _plugin: true,
+          _example: { "password" => "hunter2!", "user" => "bolt" }
+        }
+      }.freeze
+
+      # Options that are available in a bolt.yaml file
+      BOLT_OPTIONS = %w[
+        apply_settings
+        color
+        compile-concurrency
+        concurrency
+        format
+        hiera-config
+        inventoryfile
+        log
+        modulepath
+        plugin_hooks
+        plugins
+        puppetdb
+        puppetfile
+        save-rerun
+        trusted-external-command
+      ].freeze
+
+      # Options that are available in a bolt-defaults.yaml file
+      BOLT_DEFAULTS_OPTIONS = %w[
+        color
+        compile-concurrency
+        concurrency
+        format
+        inventory-config
+        log
+        plugin_hooks
+        plugins
+        puppetdb
+        puppetfile
+        save-rerun
+      ].freeze
+
+      # Options that are available in a bolt-project.yaml file
+      BOLT_PROJECT_OPTIONS = %w[
+        apply_settings
+        color
+        compile-concurrency
+        concurrency
+        format
+        hiera-config
+        inventoryfile
+        log
+        modulepath
+        name
+        plans
+        plugin_hooks
+        plugins
+        puppetdb
+        puppetfile
+        save-rerun
+        tasks
+        trusted-external-command
+      ].freeze
+    end
+  end
+end