Supported plugins

The following plugins are supported and maintained by Bolt. Supported plugins are shipped with Bolt packages and do not need to be installed separately.

Reference plugins

Reference plugins fetch data from an external source and store it in a static data object. You can use reference plugins in configuration files, inventory files, and plans.


Plugin	Description	Documentation
`aws_inventory`	Generate targets from Amazon Web Services EC2 instances.	aws_inventory
`azure_inventory`	Generate targets from Azure VMs and VM scale sets.	azure_inventory
`env_var`	Read values stored in environment variables.	env_var
`gcloud_inventory`	Generate targets from Google Cloud compute engine instances.	gcloud_inventory
`pkcs7`	Decrypt ciphertext.	pkcs7
`prompt`	Prompt the user for a sensitive value.	prompt
`puppetdb`	Query PuppetDB for a group of targets.	puppetdb
`task`	Run a task as a plugin.	task
`terraform`	Generate targets from local and remote Terraform state files.	terraform
`vault`	Access secrets from a Key/Value engine on a Hashicorp Vault server.	vault
`yaml`	Compose multiple YAML files into a single file.	yaml

Secret plugins

Use secret plugins to create keys for encryption and decryption, to encrypt plaintext, or to decrypt ciphertext. Secret plugins are used by Bolt's secret command.


Plugin	Description	Documentation
`pkcs7`	Generate key pairs, encrypt plaintext, and decrypt ciphertext.	pkcs7

Puppet library plugins

Puppet library plugins ensure that the Puppet library is installed on a target when a plan calls the apply_prep function.


Plugin	Description	Documentation
`puppet_agent`	Install Puppet libraries on target nodes when a plan calls `apply_prep`.	puppet_agent

Built-in plugins

The following plugins are built into Bolt and are not available in modules.

`env_var`

The env_var plugin allows users to read values stored in environment variables and load them into an inventory or configuration file.

Parameters

The following parameters are available to the env_var plugin:


Parameter	Description	Type	Default
`var`	Required. The name of the environment variable to read from.	`String`	None
`default`	A value to use if the environment variable `var` isn't set.	`String`	None
`optional`	Unless `true`, `env_var` raises an error when the environment variable `var` does not exist. When `optional` is `true` and `var` does not exist, env_var returns `nil`.	`Boolean`	`false`
`json`	The environment variable value is encoded in a json string, parse it and use the resolved data.	`Boolean`	`false`

Example usage

Looking up a value from an environment variable in an inventory file:

targets:
  - target1.example.com
config:
  ssh:
    user: bolt
    password:
      _plugin: env_var
      var: BOLT_PASSWORD

`prompt`

The prompt plugin allows users to interactively enter sensitive configuration information on the CLI instead of storing that data in the inventory file. Data is looked up when the value is needed for the target. Once the value has been stored, it is re-used for the rest of the Bolt run.

Parameters

The following parameter is available to the prompt plugin:


Parameter	Description	Type	Default
`message`	Required. The text to show when prompting the user.	`String`	None

Example usage

Prompting for a password in an inventory file:

targets:
  - target1.example.com
config:
  ssh:
    password:
      _plugin: prompt
      message: Enter your SSH password

`puppetdb`

The puppetdb plugin queries PuppetDB for a group of targets.

If you require target-specific configuration, you can use the puppetdb plugin to look up configuration values for the alias, config, facts, features, name, uri and vars inventory options for each target. Set these values in the target_mapping field. The fact look up values can be either certname to reference the [certname] of the target, or a PQL dot notation facts string such as facts.os.family to reference a fact value. Dot notation is required for both structured and unstructured facts.

Parameters

The following parameters are available to the puppetdb plugin:


Parameter	Description	Type	Default
`query`	Required. A string containing a PQL query or an array containing a PuppetDB AST format query.	`String`	None
`target_mapping`	Required. A hash of target attributes (`name`, `uri`, `config`) to populate with fact lookup values.	`Hash`	None

Note: If neither name nor uri is specified in target_mapping, then uri is set to certname.

Available fact paths

The following values/patterns are available to use for looking up facts in the target_mapping field:


Key	Description
`certname`	The certname of the node returned from PuppetDB. This is short hand for doing: `facts.trusted.certname`.
`facts.*`	PQL dot notation facts string such as `facts.os.family` to reference fact value. Dot notation is required for both structured and unstructured facts.

Example usage

Look up targets with the fact osfamily: RedHat and the following configuration values:

The alias with the fact hostname
The name with the fact certname
A target fact called custom_fact with the custom_fact from PuppetDB
A feature from the fact custom_feature
The SSH hostname with the fact networking.interfaces.en0.ipaddress
The puppetversion variable from the fact puppetversion

targets:
  - _plugin: puppetdb
    query: "inventory[certname] { facts.osfamily = 'RedHat' }"
    target_mapping:
      alias: facts.hostname
      name: certname
      facts:
        custom_fact: facts.custom_fact
      features:
        - facts.custom_feature
      config:
        ssh:
          host: facts.networking.interfaces.en0.ipaddress
      vars:
        puppetversion: facts.puppetversion

`task`

The task plugin lets Bolt run a task as a plugin and extracts the value key from the task output to use as the plugin value. Plugin tasks run on the localhost target without access to any configuration defined in an inventory file, but with access to any parameters that you've configured.

For example, you could run a task plugin that collects target names from a JSON file and interpolates them into a target array in your inventory file.

Parameters

The following parameters are available to the task plugin:


Key	Description	Type	Default
`task`	Required. The name of the task to run.	`String`	None
`parameters`	The parameters to pass to the task.	`Hash`	None

Example usage

Loading targets with a my_json_file::targets task and a password with a my_db::secret_lookup task:

targets:
  - _plugin: task
    task: my_json_file::targets
    parameters:
      file: /etc/targets/data.json
      environment: production
      app: my_app
config:
  ssh:
    password:
      _plugin: task
      task: my_db::secret_lookup
      parameters:
        key: ssh_password