bolt 2.37.0 → 2.44.0

data/lib/bolt/config/options.rb

@@ -50,81 +50,40 @@ module Bolt
         }
       }.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.
+      # Definitions used to validate config options.
+      # https://github.com/puppetlabs/bolt/blob/main/schemas/README.md
       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: {
+            "evaltrace" => {
+              description: "Whether each resource should log when it is being evaluated.",
+              type: [TrueClass, FalseClass],
+              _example: true,
+              _default: false
+            },
+            "log_level" => {
+              description: "The log level for logs in apply reports from Puppet. These can be seen "\
+                           "in ApplyResults.",
+              type: String,
+              enum: %w[debug info notice warning err alert emerg crit],
+              _example: "debug",
+              _default: "notice"
+            },
             "show_diff" => {
               description: "Whether to log and report a contextual diff.",
               type: [TrueClass, FalseClass],
               _example: true,
               _default: false
+            },
+            "trace" => {
+              description: "Whether to print stack traces on some errors. Will print internal Ruby "\
+                           "stack trace interleaved with Puppet function frames.",
+              type: [TrueClass, FalseClass],
+              _example: true,
+              _default: false
             }
           },
           _plugin: false,
@@ -135,11 +94,33 @@ module Bolt
                        "plan function or the `bolt apply` command.",
           type: Hash,
           properties: {
+            "evaltrace" => {
+              description: "Whether each resource should log when it is being evaluated. This allows "\
+                           "you to interactively see exactly what is being done.",
+              type: [TrueClass, FalseClass],
+              _example: true,
+              _default: false
+            },
+            "log_level" => {
+              description: "The log level for logs in apply reports from Puppet. These can be seen "\
+                           "in ApplyResults.",
+              type: String,
+              enum: %w[debug info notice warning err alert emerg crit],
+              _example: "debug",
+              _default: "notice"
+            },
             "show_diff" => {
               description: "Whether to log and report a contextual diff.",
               type: [TrueClass, FalseClass],
               _example: true,
               _default: false
+            },
+            "trace" => {
+              description: "Whether to print stack traces on some errors. Will print internal Ruby "\
+                           "stack trace interleaved with Puppet function frames.",
+              type: [TrueClass, FalseClass],
+              _example: true,
+              _default: false
             }
           },
           _plugin: false
@@ -167,6 +148,17 @@ module Bolt
           _example: 50,
           _default: "100 or 1/7 the ulimit, whichever is lower."
         },
+        "disable-warnings" => {
+          description: "An array of IDs of warnings to suppress. Warnings with a matching ID will not be logged "\
+                       "by Bolt. If you are upgrading Bolt to a new major version, you should re-enable all warnings "\
+                       "until you have finished upgrading.",
+          type: Array,
+          items: {
+            type: String
+          },
+          _plugin: false,
+          _example: ["powershell_2"]
+        },
         "format" => {
           description: "The format to use when printing results.",
           type: String,
@@ -272,6 +264,41 @@ module Bolt
           _example: ["~/.puppetlabs/bolt/modules", "~/.puppetlabs/bolt/site-modules"],
           _default: ["project/modules", "project/site-modules", "project/site"]
         },
+        "module-install" => {
+          description: "Options that configure where Bolt downloads modules from. This option is only used when "\
+                       "installing modules using the `bolt module add|install` commands and "\
+                       "`Add|Install-BoltModule` cmdlets.",
+          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 Forge operations.",
+                  type: String,
+                  format: "uri",
+                  _example: "https://my-forge-proxy.com:8080"
+                }
+              },
+              _example: { "baseurl" => "https://forge.example.com", "proxy" => "https://my-forge-proxy.com:8080" }
+            },
+            "proxy" => {
+              description: "The HTTP proxy to use for Git and Forge operations.",
+              type: String,
+              format: "uri",
+              _example: "https://my-proxy.com:8080"
+            }
+          },
+          _plugin: false
+        },
         "modules" => {
           description: "A list of module dependencies for the project. Each dependency is a map of data specifying "\
                        "the module to install. To install the project's module dependencies, run the `bolt module "\
@@ -287,6 +314,10 @@ module Bolt
                     description: "The name of the module.",
                     type: String
                   },
+                  "resolve" => {
+                    description: "Whether to resolve the module's dependencies when installing modules.",
+                    type: [TrueClass, FalseClass]
+                  },
                   "version_requirement" => {
                     description: "The version requirement for the module. Accepts a specific version (1.2.3), version "\
                                  "shorthand (1.2.x), or a version range (>= 1.2.0).",
@@ -301,9 +332,17 @@ module Bolt
                     description: "The URL to the public git repository.",
                     type: String
                   },
+                  "name" => {
+                    description: "The name of the module. Required when `resolve` is `false`.",
+                    type: String
+                  },
                   "ref" => {
                     description: "The git reference to check out. Can be either a branch, tag, or commit SHA.",
                     type: String
+                  },
+                  "resolve" => {
+                    description: "Whether to resolve the module's dependencies when installing modules.",
+                    type: [TrueClass, FalseClass]
                   }
                 }
               }
@@ -377,49 +416,57 @@ module Bolt
             "cacert" => {
               description: "The path to the ca certificate for PuppetDB.",
               type: String,
-              _example: "/etc/puppetlabs/puppet/ssl/certs/ca.pem"
+              _example: "/etc/puppetlabs/puppet/ssl/certs/ca.pem",
+              _plugin: true
             },
             "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"
+              _example: "/etc/puppetlabs/puppet/ssl/certs/my-host.example.com.pem",
+              _plugin: true
             },
             "connect_timeout" => {
               description: "How long to wait in seconds when establishing connections with PuppetDB.",
               type: Integer,
               minimum: 1,
               _default: 60,
-              _example: 120
+              _example: 120,
+              _plugin: true
             },
             "key" => {
               description: "The private key for the certificate.",
               type: String,
-              _example: "/etc/puppetlabs/puppet/ssl/private_keys/my-host.example.com.pem"
+              _example: "/etc/puppetlabs/puppet/ssl/private_keys/my-host.example.com.pem",
+              _plugin: true
             },
             "read_timeout" => {
               description: "How long to wait in seconds for a response from PuppetDB.",
               type: Integer,
               minimum: 1,
               _default: 60,
-              _example: 120
+              _example: 120,
+              _plugin: true
             },
             "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-puppetdb-server.com:8081`.",
               type: Array,
-              _example: ["https://puppet.example.com:8081"]
+              _example: ["https://puppet.example.com:8081"],
+              _plugin: true
             },
             "token" => {
               description: "The path to the PE RBAC Token.",
               type: String,
-              _example: "~/.puppetlabs/token"
+              _example: "~/.puppetlabs/token",
+              _plugin: true
             }
           },
           _plugin: true
         },
         "puppetfile" => {
-          description: "A map containing options for the `bolt puppetfile install` command.",
+          description: "A map containing options for the `bolt puppetfile install` command and "\
+                       "`Install-BoltPuppetfile` cmdlet.",
           type: Hash,
           properties: {
             "forge" => {
@@ -434,21 +481,23 @@ module Bolt
                   _example: "https://forge.example.com"
                 },
                 "proxy" => {
-                  description: "The HTTP proxy to use for Git and Forge operations.",
+                  description: "The HTTP proxy to use for Forge operations.",
                   type: String,
                   format: "uri",
-                  _example: "https://forgeapi.example.com"
+                  _example: "https://my-forge-proxy.com:8080"
                 }
               },
-              _example: { "baseurl" => "https://forge.example.com", "proxy" => "https://forgeapi.example.com" }
+              _example: { "baseurl" => "https://forge.example.com", "proxy" => "https://my-forge-proxy.com:8080" }
             },
             "proxy" => {
               description: "The HTTP proxy to use for Git and Forge operations.",
               type: String,
               format: "uri",
-              _example: "https://forgeapi.example.com"
+              _example: "https://my-proxy.com:8080"
             }
           },
+          _deprecation: "This option will be removed in Bolt 3.0. Update your project to use the module "\
+                        "management feature. For more information, see https://pup.pt/bolt-module-migrate.",
           _plugin: false
         },
         "save-rerun" => {
@@ -460,6 +509,14 @@ module Bolt
           _example: false,
           _default: true
         },
+        "spinner" => {
+          description: "Whether to print a spinner to the console for long-running Bolt operations.",
+          type: [TrueClass, FalseClass],
+          _plugin: false,
+          _example: false,
+          _default: true
+        },
+
         "tasks" => {
           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 "\
@@ -494,7 +551,7 @@ module Bolt
                        "specified in the URI.",
           type: String,
           enum: TRANSPORT_CONFIG.keys,
-          _plugin: false,
+          _plugin: true,
           _example: "winrm",
           _default: "ssh"
         },
@@ -520,6 +577,7 @@ module Bolt
         "remote" => {
           description: "A map of configuration options for the remote transport.",
           type: Hash,
+          additionalProperties: true,
           _plugin: true,
           _example: { "run-on" => "proxy_target" }
         },
@@ -555,6 +613,7 @@ module Bolt
         puppetdb
         puppetfile
         save-rerun
+        spinner
         trusted-external-command
       ].freeze
 
@@ -563,9 +622,11 @@ module Bolt
         color
         compile-concurrency
         concurrency
+        disable-warnings
         format
         inventory-config
         log
+        module-install
         plugin-cache
         plugin-hooks
         plugin_hooks
@@ -573,6 +634,7 @@ module Bolt
         puppetdb
         puppetfile
         save-rerun
+        spinner
       ].freeze
 
       # Options that are available in a bolt-project.yaml file
@@ -582,11 +644,13 @@ module Bolt
         color
         compile-concurrency
         concurrency
+        disable-warnings
         format
         hiera-config
         inventoryfile
         log
         modulepath
+        module-install
         modules
         name
         plans
@@ -597,6 +661,7 @@ module Bolt
         puppetdb
         puppetfile
         save-rerun
+        spinner
         tasks
         trusted-external-command
       ].freeze

data/lib/bolt/config/transport/base.rb

@@ -2,7 +2,7 @@
 
 require 'bolt/error'
 require 'bolt/util'
-require 'bolt/config/validator'
+require 'bolt/validator'
 require 'bolt/config/transport/options'
 
 module Bolt
@@ -125,7 +125,7 @@ module Bolt
 
         # Validation defaults to just asserting the option types
         private def validate
-          Bolt::Config::Validator.new.validate(@config.compact, self.class.schema.fetch(:properties))
+          Bolt::Validator.new.validate(@config.compact, self.class.schema)
         end
       end
     end

data/lib/bolt/config/transport/local.rb

@@ -8,6 +8,7 @@ module Bolt
     module Transport
       class Local < Base
         WINDOWS_OPTIONS = %w[
+          bundled-ruby
           cleanup
           interpreters
           tmpdir

data/lib/bolt/config/transport/options.rb

@@ -6,73 +6,8 @@ module Bolt
       module Options
         LOGIN_SHELLS = %w[sh bash zsh dash ksh powershell].freeze
 
-        # The following constants define the various configuration options available to Bolt's
-        # transports. 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.
-        #
-        #   :propertyNames  Hash        A hash that defines the properties that an option's property
-        #                               names must adhere to.
-        #
-        #   :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.
+        # Definitions used to validate config options.
+        # https://github.com/puppetlabs/bolt/blob/main/schemas/README.md
         TRANSPORT_OPTIONS = {
           "basic-auth-only" => {
             type: [TrueClass, FalseClass],
@@ -81,6 +16,13 @@ module Bolt
             _default: false,
             _example: true
           },
+          "bundled-ruby" => {
+            description: "Whether to use the Ruby bundled with Bolt packages for local targets.",
+            type: [TrueClass, FalseClass],
+            _plugin: false,
+            _example: true,
+            _default: false
+          },
           "cacert" => {
             type: String,
             description: "The path to the CA certificate.",
@@ -201,7 +143,8 @@ module Bolt
                          "`task.py`) and the extension is case sensitive. When a target's name is `localhost`, "\
                          "Ruby tasks run with the Bolt Ruby interpreter by default.",
             additionalProperties: {
-              type: String
+              type: String,
+              _plugin: false
             },
             propertyNames: {
               pattern: "^.?[a-zA-Z0-9]+$"
@@ -310,6 +253,13 @@ module Bolt
             _plugin: true,
             _example: "jump.example.com"
           },
+          "read-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds when making requests to the Orchestrator.",
+            minimum: 1,
+            _plugin: true,
+            _example: 15
+          },
           "realm" => {
             type: String,
             description: "The Kerberos realm (Active Directory domain) to authenticate against.",