Configuring Bolt

Sections

Bolt has many options and features that can be configured to suit your project's needs. In general, Bolt configuration falls into four categories:

  • Bolt behavior: Configure how Bolt itself runs, such as the format to use when displaying output or how many threads to use when connecting to targets.

  • Projects: Configure the Bolt project that you are running Bolt in, such as the path to an inventory file or the path to a Hiera configuration file.

  • Transports: Configure the transports that Bolt uses to connect to targets, such as the path to a private key when using SSH or the port to connect to when using WinRM.

  • Inventory data: Group and configure the targets that you connect to and run commands on with Bolt.

Each type of configuration can be set in a different file. You can configure Bolt's options and features at a project level, a user level, or a system-wide level. Unless your use case requires setting user-specific or system-wide configurations, configure Bolt at the project level.

Type of Configurationinventory.yamlbolt-project.yamlbolt-defaults.yaml
Bolt behavior
Projects
Transports
Inventory data
Configuration levelprojectprojectuser, system-wide

Project-level configuration

Most of the time, you'll only need to set configuration at the project level. You can set all configurable options in Bolt at the project level, and any options you set within a project only apply to that project.

Bolt loads project-level configuration files from the root of your Bolt project directory. If it can't find a project directory, Bolt uses the default project directory: ~/.puppetlabs/bolt/.

You can set project-level configuration in three files:

  • For Bolt configuration, use bolt-project.yaml.

  • For inventory configuration, use inventory.yaml.

  • You can set all configuration in a bolt.yaml file at the root of your project directory. The project-level bolt.yaml file is on the path towards deprecation and will be removed in a future version of Bolt. Use bolt-project.yaml and inventory.yaml files instead.

The preferred method for setting project-level configuration is to use a combination of bolt-project.yaml and inventory.yaml files. This maintains a clear distinction between Bolt configuration and inventory configuration.

bolt-project.yaml

Note: The bolt-project.yaml file is experimental and is subject to change. You can read more about Bolt projects in Experimental features.

Filepath: <project-directory>/bolt-project.yaml

The project configuration file supports options that configure how Bolt behaves, such as how many threads it can use when running commands on targets. You can also use bolt-project.yaml to configure different components of the project, such as a list of plans and tasks that are visible to the user. Any directory containing a bolt-project.yaml file is automatically considered a Project directory.

Project configuration files take precedence over bolt.yaml files. If a project directory contains both files, Bolt will only load and read configuration from bolt-project.yaml.

You can view a full list of the available options in bolt-project.yaml options.

inventory.yaml

Filepath: <project-directory>/inventory.yaml

The inventory file is a structured data file that contains groups of targets that you can run Bolt commands on, as well as configuration for the transports used to connect to the targets. Most projects will include an inventory file.

Inventory configuration can be set at multiple levels in an inventory file under a config option. You can set the following options under config:

  • transport

  • docker

  • local

  • pcp

  • remote

  • ssh

  • winrm

You can view a full list of the available options in inventory.yaml fields.

DEPRECATED: bolt.yaml

Note: The project-level bolt.yaml file is on the path towards deprecation and will be removed in a future version of Bolt. Use bolt-project.yaml and inventory.yaml files instead.

Filepath: <project-directory>/bolt.yaml

The Bolt configuration file can be used to set all available configuration options, including default inventory configuration options. Any directory containing a bolt.yaml file is automatically considered a Project directory.

You can view a full list of the available options in bolt.yaml options.

User-level configuration

Use this level to set configuration that should apply to all projects for a particular user. Options that you might set at the user-level include paths to private keys, credentials for a plugin, or default inventory configuration that is common to all of your projects. You can set most configurable options in Bolt at the user level.

You can set user-level configuration in two files:

  • Use bolt-defaults.yaml for configuration that is not project-specific.

  • You can set all configuration in a bolt.yaml file. The user-level bolt.yaml file is deprecated and will be removed in a future version of Bolt. Use bolt-defaults.yaml instead.

The preferred method for setting user-level configuration is to use a bolt-defaults.yaml file. This file does not allow you to set project-specific configuration, such as the path to an inventory file, and is less likely to lead to errors where Bolt loads content from another project.

bolt-defaults.yaml

Filepath: ~/.puppetlabs/etc/bolt/bolt-defaults.yaml

The defaults configuration file supports most of Bolt's configuration options, with the exception of options that are project-specific such as inventoryfile and modulepath.

The bolt-defaults.yaml file takes precedence over a bolt.yaml file in the same directory. If the directory contains both files, Bolt will only load and read configuration from bolt-defaults.yaml.

You can view a full list of the available options in bolt-defaults.yaml options.

DEPRECATED: bolt.yaml

Note: The user-level bolt.yaml file is deprecated and will be removed in a future version of Bolt. Use a bolt-defaults.yaml file instead.

Filepath: ~/.puppetlabs/etc/bolt/bolt.yaml

The Bolt configuration file can be used to set all available configuration options, including project-specific configuration options.

You can view a full list of the available options in bolt.yaml options.

System-wide configuration

Use this level to set configuration that applies to all users and all projects. This might include configuration for connecting to an organization's Forge proxy, the number of threads Bolt should use when connecting to targets, or setting credentials for connecting to PuppetDB. You can set most configurable Bolt options at the system level.

System-wide configuration can be set in two files.

  • Use bolt-defaults.yaml for configuration that is not project-specific.

  • You can set all configuration in a bolt.yaml file. The system-level bolt.yaml file is deprecated and will be removed in a future version of Bolt. Use bolt-defaults.yaml instead.

The preferred method for setting user-level configuration is to use a bolt-defaults.yaml file. This file does not allow you to set project-specific configuration, such as the path to an inventory file, and is less likely to lead to errors where content from another project is loaded.

bolt-defaults.yaml

\*nix Filepath: /etc/puppetlabs/bolt/bolt-defaults.yaml

Windows Filepath: %PROGRAMDATA%\PuppetLabs\bolt\etc\bolt-defaults.yaml

The defaults configuration file supports most of Bolt's configuration options, with the exception of options that are project-specific such as inventoryfile and modulepath.

The bolt-defaults.yaml file takes precedence over a bolt.yaml file in the same directory. If the directory contains both files, Bolt will only load and read configuration from bolt-defaults.yaml.

You can view a full list of the available options in bolt-defaults.yaml options.

DEPRECATED: bolt.yaml

Note: The system-wide bolt.yaml file is deprecated and will be removed in a future version of Bolt. Use a bolt-defaults.yaml file instead.

\*nix Filepath: /etc/puppetlabs/bolt/bolt.yaml

Windows Filepath: %PROGRAMDATA%\PuppetLabs\bolt\etc\bolt.yaml

You can set all available configuration options in bolt.yaml, including project-specific configuration options.

You can view a full list of the available options in bolt.yaml options.

Configuration precedence

Bolt uses the following precedence when interpolating configuration settings, from highest precedence to lowest:

  • Target URI (i.e. ssh://user:password@hostname:port)

  • Inventory file options

  • Command line flags

  • Project-level configuration file

  • User-level configuration file

  • System-wide configuration file

  • SSH configuration file options (e.g. ~/.ssh/config)

Merge strategy

When merging configurations, Bolt's strategy is to shallow merge any options that accept hashes and to overwrite any options that do not accept hashes. There are two exceptions to this strategy:

Transport configuration merge strategy

Transport configuration is deep merged.

For example, given this SSH configuration in an inventory file:

# ~/.puppetlabs/bolt/inventory.yaml
config:
  ssh:
    user: bolt
    password: bolt
    host-key-check: false

And this this SSH configuration in a user configuration file:

# ~/.puppetlabs/etc/bolt/bolt-defaults.yaml
inventory-config:
  ssh:
    user: puppet
    password: puppet
    private-key: ~/path/to/key/id_rsa

The merged Bolt configuration would look like this:

ssh:
  user: bolt
  password: bolt
  host-key-check: false
  private-key: ~/path/to/key/id_rsa

Plugin configuration merge strategy

The plugins option accepts a hash where each key is the name of a plugin and its value is a hash of configuration options for the plugin. When merging configurations, the configuration for individual plugins is shallow merged.

Note: If a plugin is configured in one file, but is not configured in a file with a higher precedence, the configuration for the plugin will still be present in the merged configuration.

For example, given this plugin configuration in a project configuration file:

# ~/.puppetlabs/bolt/bolt-project.yaml
plugins:
  vault:
    auth:
      method: userpass
      user: bolt
      pass: bolt

And this plugin configuration in a system-wide configuration file:

# /etc/puppetlabs/bolt/bolt-defaults.yaml
plugins:
  aws_inventory:
    credentials: /etc/aws/credentials
  vault:
    server_url: http://example.com
    auth:
      method: token
      token: xxxx-xxxx-xxxx-xxxx

The merged Bolt configuration would look like this:

plugins:
  aws_inventory:
    credentials: /etc/aws/credentials
  vault:
    server_url: 'http://example.com'
    auth:
      method: userpass
      user: bolt
      pass: bolt

📖 Related information

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.