Module: Bolt::Config::Options

Included in:

Bolt::Config

Defined in:

lib/bolt/config/options.rb

Constant Summary

TRANSPORT_CONFIG =

Transport config classes. Used to load default transport config which gets passed along to the inventory.

{
  'docker' => Bolt::Config::Transport::Docker,
  'jail'   => Bolt::Config::Transport::Jail,
  'local'  => Bolt::Config::Transport::Local,
  'lxd'    => Bolt::Config::Transport::LXD,
  'podman' => Bolt::Config::Transport::Podman,
  'remote' => Bolt::Config::Transport::Remote,
  'ssh'    => Bolt::Config::Transport::SSH,
  'winrm'  => Bolt::Config::Transport::WinRM
}.freeze

PLUGIN =

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" => {
    description: "A plugin reference.",
    type: "object",
    required: ["_plugin"],
    properties: {
      "_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
          }
        }
      }
    }
  }
}.freeze

PUPPETDB_OPTIONS =

PuppetDB options.

{
  "cacert" => {
    description: "The path to the ca certificate for PuppetDB.",
    type: String,
    _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",
    _plugin: true
  },
  "connect_timeout" => {
    description: "How long to wait in seconds when establishing connections with PuppetDB.",
    type: Integer,
    minimum: 1,
    _default: 60,
    _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",
    _plugin: true
  },
  "read_timeout" => {
    description: "How long to wait in seconds for a response from PuppetDB.",
    type: Integer,
    minimum: 1,
    _default: 60,
    _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"],
    _plugin: true
  },
  "token" => {
    description: "The path to the PE RBAC Token.",
    type: String,
    _example: "~/.puppetlabs/token",
    _plugin: true
  }
}.freeze

OPTIONS =

Definitions used to validate config options. github.com/puppetlabs/bolt/blob/main/schemas/README.md

{
  "analytics" => {
    description: "Whether to disable analytics. Setting this option to 'false' in the system-wide " \
                 "or user-level configuration will disable analytics for all projects, even if this " \
                 "option is set to 'true' at the project level.",
    type: [TrueClass, FalseClass],
    _example: false
  },
  "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. 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
  },
  "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."
  },
  "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,
    enum: %w[human json rainbow],
    _plugin: false,
    _example: "json",
    _default: "human"
  },
  "future" => {
    description: "Enable new Bolt features that may include breaking changes.",
    type: Hash,
    properties: {
      "file_paths" => {
        description: "Load scripts from the `scripts/` directory of a module.",
        type: [TrueClass, FalseClass],
        _example: true,
        _default: false,
        _deprecation: "Bolt no longer honors this option and enables loading scripts from the scripts " \
                      "directory by default."
      },
      "script_interpreter" => {
        description: "Use a target's [`interpreters` configuration](bolt_transports_reference.md#interpreters) " \
                     "when running a script.",
        type: [TrueClass, FalseClass],
        _example: true,
        _default: false
      }
    },
    _plugin: false,
    _example: { 'script_interpreter' => true }
  },
  "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: {}
  },
  "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 " \
                 "`~/.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. Set the value to " \
                 "`disable` to remove a log file defined at an earlier level of the config hierarchy. By " \
                 "default, Bolt logs to a bolt-debug.log file in the Bolt project directory.",
    type: Hash,
    properties: {
      "console" => {
        description: "Configuration for logs output to the console.",
        type: [String, Hash],
        enum: ['disable'],
        properties: {
          "level" => {
            description: "The type of information to log.",
            type: String,
            enum: %w[trace debug error info warn fatal],
            _default: "warn"
          }
        }
      }
    },
    additionalProperties: {
      description: "Configuration for the logfile output.",
      type: [String, Hash],
      enum: ['disable'],
      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[trace debug error info warn fatal],
          _default: "warn"
        }
      }
    },
    _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"]
  },
  "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 for configuring connections to a Forge host.",
        type: Hash,
        properties: {
          "authorization_token" => {
            description: "The token used to authorize requests to the Forge host. Must also specify " \
                         "`baseurl` when using this option.",
            type: String,
            _example: "Bearer eyJhbGciOiJIUzI1NiIsInR5c...",
            _plugin: true
          },
          "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: {
          "authorization_token" => "Bearer eyJhbGciOiJIUzI1NiIsInR5c...",
          "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 " \
                 "install` command. For more information about specifying modules, see [the " \
                 "documentation](https://pup.pt/bolt-module-specs).",
    type: Array,
    items: {
      type: [Hash, String],
      oneOf: [
        {
          required: ["name"],
          properties: {
            "name" => {
              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).",
              type: String
            }
          }
        },
        {
          required: %w[git ref],
          properties: {
            "git" => {
              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]
            }
          }
        }
      ]
    },
    _plugin: false,
    _default: [],
    _example: [
      "puppetlabs-facts",
      { "name" => "puppetlabs-mysql" },
      { "name" => "puppetlabs-apache", "version_requirement" => "5.5.0" },
      { "name" => "puppetlabs-puppetdb", "version_requirement" => "7.x" },
      { "name" => "puppetlabs-firewall", "version_requirement" => ">= 1.0.0 < 3.0.0" },
      { "git" => "https://github.com/puppetlabs/puppetlabs-apt", "ref" => "7.6.0" }
    ]
  },
  "name" => {
    description: "The name of the Bolt project. When this option is configured, the project is considered a " \
                 "[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 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 " \
                 "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", "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: " \
                 "[`openvox_bootstrap`](https://github.com/voxpupuli/puppet-openvox_bootstrap#openvox_boostrapinstall) " \
                 "and [`task`](using_plugins.md#task).",
    type: Hash,
    _plugin: true,
    _example: { "puppet_library" => { "plugin" => "openvox_bootstrap", "version" => "1.2.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,
    additionalProperties: {
      type: Hash,
      _plugin: true
    },
    _plugin: false,
    _example: { "pkcs7" => { "keysize" => 1024 } }
  },
  "policies" => {
    description: "A list of policy names and glob patterns to filter the project's policies by. This option " \
                 "is used to specify which policies are available to a project and can be applied to targets. " \
                 "When this option is not configured, policies are not available to the project and cannot " \
                 "be applied to targets.",
    type: Array,
    _plugin: false,
    _example: ["myproject::apache", "myproject::postgres"]
  },
  "puppetdb" => {
    description: "A map containing options for [configuring the Bolt PuppetDB " \
                 "client](bolt_connect_puppetdb.md).",
    type: Hash,
    properties: PUPPETDB_OPTIONS,
    _plugin: true
  },
  "puppetdb-instances" => {
    description: "A map of named PuppetDB instances and their configuration, where keys are the name " \
                 "of a PuppetDB instance and values are maps of configuration options. For more " \
                 "information, see [Connecting Bolt to PuppetDB](bolt_connect_puppetdb.md).",
    type: Hash,
    additionalProperties: {
      type: Hash,
      properties: PUPPETDB_OPTIONS
    },
    _plugin: true
  },
  "rerunfile" => {
    description: "The path to the project's rerun file. The rerun file is used to store information " \
                 "about targets from the most recent run. Expands relative to the project directory.",
    type: String,
    _example: "/Users/bolt/project/rerun.json",
    _plugin: true
  },
  "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
  },
  "spinner" => {
    description: "Whether to print a spinner to the console for long-running Bolt operations.",
    type: [TrueClass, FalseClass],
    _plugin: false,
    _example: false,
    _default: true
  },
  "stream" => {
    description: "Whether to stream output from scripts and commands to the console. " \
                 "**This option is experimental**.",
    type: [TrueClass, FalseClass],
    _plugin: false,
    _default: false,
    _example: 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 " \
                 "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", "myproject::deploy_*"]
  },
  "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 might " \
                 "change or be removed.**",
    type: String,
    _plugin: false,
    _example: "/etc/puppetlabs/facts/trusted_external.sh"
  }
}.freeze

INVENTORY_OPTIONS =

Options that configure the inventory, specifically the default transport used by targets and the transports themselves. These options are used in bolt-defaults.yaml under ‘inventory-config’ and in inventory.yaml under ‘config’.

{
  "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: true,
    _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" }
  },
  "jail" => {
    description: "A map of configuration options for the jail transport.",
    type: Hash,
    _plugin: true,
    _example: { cleanup: false }
  },
  "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" }
  },
  "lxd" => {
    description: "A map of configuration options for the LXD transport. The LXD transport is " \
                 "experimental and might include breaking changes between minor versions.",
    type: Hash,
    _plugin: true,
    _example: { cleanup: false }
  },
  "podman" => {
    description: "A map of configuration options for the podman transport.",
    type: Hash,
    _plugin: true,
    _example: { "cleanup" => false, "tmpdir" => "/mount/tmp" }
  },
  "remote" => {
    description: "A map of configuration options for the remote transport.",
    type: Hash,
    additionalProperties: true,
    _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

CLI_OPTIONS =

Options that are available on the command line This only includes options where users can provide arbitrary values from the command-line, allowing the validator to check them

%w[
  compile-concurrency
  concurrency
  format
  log
  modulepath
  transport
].freeze

DEFAULTS_OPTIONS =

Options that are available in a bolt-defaults.yaml file

%w[
  analytics
  color
  compile-concurrency
  concurrency
  disable-warnings
  format
  inventory-config
  log
  module-install
  plugin-cache
  plugin-hooks
  plugins
  puppetdb
  puppetdb-instances
  save-rerun
  spinner
  stream
].freeze

PROJECT_OPTIONS =

Options that are available in a bolt-project.yaml file

%w[
  analytics
  apply-settings
  color
  compile-concurrency
  concurrency
  disable-warnings
  format
  future
  hiera-config
  log
  modulepath
  module-install
  modules
  name
  plans
  plugin-cache
  plugin-hooks
  plugins
  policies
  puppetdb
  puppetdb-instances
  rerunfile
  save-rerun
  spinner
  stream
  tasks
  trusted-external-command
].freeze