Version 2 of the inventory file is experimental and might experience breaking changes in future releases.

Migrating to version 2

Version 2 of the inventory file changes some terms and syntax. To convert to version 2, you must make these changes.

version: 2

The default version for inventory files is version 1. In order to have Bolt treat your inventory file as a version 2 inventory, specify version: 2 at the top level.

nodes => targets

In order to standardize terminology across Bolt and capture the breadth of possible targets, such as web services, version 2 of the inventory file uses the targets section of a group to specify its members instead of nodes.

name => uri

Changing the name key to uri results in an inventory file that matches the behavior of version 1.

In version 1 of the inventory file, Bolt treated the name field of a node as its URI. This made it impossible to specify a name that did not include the hostname of a target, which proved limiting for remote targets. In version 2, the optional uri field sets the URI for a target. Any connection information from the URI, such as a user specified by [email protected] can't be overridden with other configuration methods. If the uri is set, it's used as the default value for the name key. Every target requires a name, so either the name or uri field must be set.

If there is a bare string in the target's array, Bolt tries to resolve the string to a target defined elsewhere in the inventory. If no target has a name or alias matching the string, Bolt creates a new target with the string as its URI.

Version 2 features

These features are exclusive to version 2 of the inventory file.

Creating a node with a human readable name and IP address

With version 2 of the inventory file, you can create a node with a human readable name even when an IP address is used for connecting.

You do so by setting both a uri and name, or by setting host in the transport config in addition to the name.
targets:
  - name: my_device
    config:
      transport: remote
      remote:
        host: 192.168.100.179
  - name: my_device2
    uri: 192.168.100.179

Plugins and dynamic inventory

There are two types of plugins. The target-lookups plugin type allows dynamic target discovery when running Bolt. The config-lookup plugin type allows dynamically looking up values not explicitly stored in an inventory file.

In order to make target discovery and configuration extensible, plugins are expected to eventually be plugable but for now Bolt only ships with built-in plugins.

target-lookups plugins

target-lookups is a key at the group level that allows you to dynamically look up the targets in the node. target-lookups contains an array of target lookup objects. Each target-lookups entry must include a plugin key that defines which plugin should be used for the lookup. The rest of the keys are specific to the plugin being used. Note that config-lookup plugins are not available to set config nested under target-lookups.

PuppetDB

The PuppetDB plugin takes a query field, which is either a string containing a PQL query or an array containing a PuppetDB AST query. The query is used to determine which targets should be included in the group. If name or uri is not specified with a fact lookup, then the certname for each target in the query result will be used as the uri for the new target.
groups:
  - name: windows
    target-lookups:
      - plugin: puppetdb
        query: "inventory[certname] { facts.osfamily = 'windows' }"
    config:
      transport: winrm
  - name: redhat
    target-lookups:
      - plugin: puppetdb
        query: "inventory[certname] { facts.osfamily = 'RedHat' }"
    config:
      transport: ssh

Make sure you've configured PuppetDB.

If target-specific configuration is required, the PuppetDB plugin can be used to look up configuration values for the name, uri, and config inventory options for each target. The fact lookup 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 fact value. Dot notation is required for both structured and unstructured facts.

Note: If the name or uri values are set to a lookup, the PuppetDB plugin will not set the uri to the certname of the target.

For example, to set the user to be the user from the identity fact:

version: 2
groups:
  - name: dynamic_config
    target-lookups:
      - plugin: puppetdb
        query: "inventory[certname] { facts.osfamily = 'RedHat' }"
        config:
          ssh:
            # Lookup config from PuppetDB facts
            user: facts.identity.user
    # And include static config
    config:
      ssh:
        tmpdir: /tmp/mytmp

And to use the certname of a target as the name:

version: 2
groups:
  - name: dynamic_config
    target-lookups:
      - plugin: puppetdb
        query: "inventory[certname] { facts.osfamily = 'RedHat' }"
        name: certname
        config:
          ssh:
            # Lookup config from PuppetDB facts
            hostname: facts.networking.interfaces.en0.ipaddress

Terraform

The Terraform plugin accepts several fields:
  • dir: The directory from which to load Terraform state.

  • resource_type: The Terraform resources to match, as a regular expression.

  • uri: (Optional) The property of the Terraform resource to use as the target URI.

  • statefile: (Optional) The name of the Terraform state file to load within dir. Defaults to terraform.tfstate.

  • name: (Optional) The property of the Terraform resource to use as the target name.

  • config: A Bolt config map where each value is the Terraform property to use for that config setting.

Eitheruri or name is required. If only uri is set, then the value of uri is used as the name.
groups:
  - name: cloud-webs
    target-lookups:
      - plugin: terraform
        dir: /path/to/terraform/project1
        resource_type: google_compute_instance.web
        uri: network_interface.0.access_config.0.nat_ip
      - plugin: terraform
        dir: /path/to/terraform/project2
        resource_type: aws_instance.web
        uri: public_ip
Multiple resources with the same name are identified as <resource>.0, <resource>.1, etc.
The path to nested properties must be separated with .: for example, network_interface.0.access_config.0.nat_ip.
For example, the following truncated output creates two targets, named 34.83.150.52 and 34.83.16.240. These targets are created by matching the resources google_compute_instance.web.0 and google_compute_instance.web.1. The uri for each target is the value of their network_interface.0.access_config.0.nat_ip property, which corresponds to the externally routable IP address in Google Cloud.
google_compute_instance.web.0:
  id = web-0
  cpu_platform = Intel Broadwell
  machine_type = f1-micro
  name = web-0
  network_interface.# = 1
  network_interface.0.access_config.# = 1
  network_interface.0.access_config.0.assigned_nat_ip = 
  network_interface.0.access_config.0.nat_ip = 34.83.150.52
  network_interface.0.address = 
  network_interface.0.name = nic0
  network_interface.0.network = https://www.googleapis.com/compute/v1/projects/cloud-app1/global/networks/default
  network_interface.0.network_ip = 10.138.0.22
  project = cloud-app1
  self_link = https://www.googleapis.com/compute/v1/projects/cloud-app1/zones/us-west1-a/instances/web-0
  zone = us-west1-a
google_compute_instance.web.1:
  id = web-1
  cpu_platform = Intel Broadwell
  machine_type = f1-micro
  name = web-1
  network_interface.# = 1
  network_interface.0.access_config.# = 1
  network_interface.0.access_config.0.assigned_nat_ip = 
  network_interface.0.access_config.0.nat_ip = 34.83.16.240
  network_interface.0.address = 
  network_interface.0.name = nic0
  network_interface.0.network = https://www.googleapis.com/compute/v1/projects/cloud-app1/global/networks/default
  network_interface.0.network_ip = 10.138.0.21
  project = cloud-app1
  self_link = https://www.googleapis.com/compute/v1/projects/cloud-app1/zones/us-west1-a/instances/web-1
  zone = us-west1-a
google_compute_instance.app.1:
  id = app-1
  cpu_platform = Intel Broadwell
  machine_type = f1-micro
  name = app-1
  network_interface.# = 1
  network_interface.0.access_config.# = 1
  network_interface.0.access_config.0.assigned_nat_ip = 
  network_interface.0.access_config.0.nat_ip = 35.197.93.137
  network_interface.0.address = 
  network_interface.0.name = nic0
  network_interface.0.network = https://www.googleapis.com/compute/v1/projects/cloud-app1/global/networks/default
  network_interface.0.network_ip = 10.138.0.23
  project = cloud-app1
  self_link = https://www.googleapis.com/compute/v1/projects/cloud-app1/zones/us-west1-a/instances/app-1
  zone = us-west1-a

config-lookup plugins

Config lookup plugins are specified using the _plugin key, which allows specifying a plugin to use. The value pointed to by _plugin should be the name of the plugin to use. Currently the only acceptable use of config-lookup plugins is to set configuration values, using the _plugin key nested under non-config settings results in validation errors. Also note that the _plugin key can't be used to set config nested under target-lookups.

Prompt plugin

The prompt plugin can be used to allow users to interactively enter sensitive configuration information on the CLI instead of storing that data in the inventory file. Data is looked up only when the value is needed for the target and once the value has been stored, it is re-used for the rest of the run. The prompt plugin may be used only when nested under config and is not supported when nested under target-lookups. The prompt plugin can be used by replacing the config value with a hash that has the following keys:
  • _plugin: The value of _plugin must be prompt

  • message: The value of message must be the text to show when prompting the user on the CLI

version: 2
targets:
  - uri: 192.168.100.179
    config:
      transport: ssh
      ssh:
        user: root
        password: 
          _plugin: prompt
          message: please enter your ssh password

Inventory config

You can set transport configuration only in the inventory file. This means using a top level transport value to assign a transport to the target and all values in the section named for the transport. You can set config on targets or groups in the inventory file. Bolt performs a depth first search of targets, followed by a search of groups, and uses the first value it finds. Nested hashes are merged.

This inventory file example defines two top-level groups: ssh_targets and win_targets. The ssh_targets group contains two other groups: webservers and memcached. Five targets are configured to use ssh transport and four other nodes to use WinRM transport.

groups:
  - name: ssh_targets
    groups:
      - name: webservers
        targets:
          - name: my_node1
            uri: 192.168.100.179
          - 192.168.100.180
          - 192.168.100.181
      - name: memcached
        targets:
          - 192.168.101.50
          - 192.168.101.60
        config:
          ssh:
            user: root
    config:
      transport: ssh
      ssh:
        user: centos
        private-key: ~/.ssh/id_rsa
        host-key-check: false
  - name: win_targets
    groups:
      - name: domaincontrollers
        targets:
          - 192.168.110.10
          - 192.168.110.20
      - name: testservers
        targets:
          - 172.16.219.20
          - 172.16.219.30
        config:
          winrm:
            user: vagrant
            password: vagrant
            ssl: false
    config:
      transport: winrm
      winrm:
        user: DOMAIN\opsaccount
        password: [email protected]
        ssl: true

Override a user for a specific target

targets:
  - uri: linux1.example.com
    config:
      ssh:
        user: me

Provide an alias to a target

The inventory can be used to create aliases to refer to a target. Aliases can be useful to refer to nodes with long or complicated names, like db.uswest.acme.example.com, or for targets that include protocol or port for uniqueness, such as 127.0.0.1:2222 and 127.0.0.1:2223. Aliases can also be useful when generating targets in a dynamic environment to give generated targets stable names to refer to.

An alias can be a single name or list of names. Each alias must match the regex /[a-zA-Z]\w+/. When using Bolt, you may refer to a target by its alias anywhere the target name would be applicable, such as the --targets command line argument or a TargetSpec.
targets:
  - uri: linux1.example.com
    alias: linux1
    config:
      ssh:
        port: 2222

Aliases must be unique across the entire inventory. You can use the same alias multiple places, but they must all refer to the same target. Alias names must not match any group or target names used in the inventory.

A list of targets may refer to a target by its alias, for example:
targets:
  - uri: 192.168.110.10
    alias: linux1
groups:
  - name: group1
    targets:
      - linux1

Inventory facts, vars, and features

In addition to config values you can store information relating to facts, vars and features for targets in the inventory. facts represent observed information about the target including what can be collected by Facter. vars contain arbitrary data that may be passed to run\_\* functions or used for logic in plans. features represent capabilities of the target that can be used to select a specific task implementation.

groups:
  - uri: centos_targets
    targets:
      - foo.example.com
      - bar.example.com
      - baz.example.com
    facts:
      operatingsystem: CentOS
  - name: production_targets
    vars:
      environment: production
    features: ['puppet-agent']

Objects

The inventory file uses the following objects.

Config
A config is a map that contains transport specific configuration options.
Group

A group is a map that requires a name and can contain any of the following:

  • targets : Array[Node]

  • groups : Groups object
  • config : Config object

  • facts : Facts object

  • vars : Vars object

  • features : Array[Feature]

A group name must match the regular expression values /[a-zA-Z]\w+/. These are the same values used for environments.

A group may contain other groups. Any nodes in the nested groups will also be in the parent group. The configuration of nested groups will override the parent group.

Groups
An array of group objects.
Facts
A map of fact names and values. Values may include arrays or nested maps.
Feature
A string describing a feature of the target.
Target
A target can be just the string of its target URI or a map that requires a name key and can contain a config. For example, a target block can contain any of the following:
"host1.example.com"
uri: "host1.example.com"
uri: "host1.example.com"
config:
					   transport: "ssh"
If the target entry is a map, it may contain any of the following:
  • alias : String or Array[String]

  • config : Config object

  • facts : Facts object

  • vars : Vars object

  • features : Array[Feature]

Target name
The name used to refer to a target.
Targets
An array of target objects.
Vars
A map of value names and values. Values may include arrays or nested maps.

File format

The inventory file is a yaml file that contains a single group. This group can be referred to as "all". In addition to the normal group fields, the top level has an inventory file version key that defaults to 1.

Precedence

If a target specifies a uri or is created from a URI string any URI-based configuration information like host, transport or port will override config values even those defined in the same block. For config values, the first value found for a target is used. Node values take precedence over group values and are searched first. Values are searched for in a depth first order. The first item in an array is searched first.

Configure transport for targets.

groups:
  - name: linux
    targets:
      - linux1.example.com
      - linux2.example.com
      - linux3.example.com
  - name: win
    targets:
      - win1.example.com
      - win2.example.com
      - win3.example.com
    config:
      transport: winrm

Configure login and escalation for a specific target.

targets:
  - uri: host1.example.com
    config:
      ssh:
          user: me
          run-as: root

Remote targets

Configure a remote target. When using the remote transport, the protocol of the target name does not have to map to the transport if you set the transport config option. This is useful if the target is an http API, for example:
targets:
  - host1.example.com
  - uri: https://user1:[email protected]
    config:
      transport: remote
      remote:
        # The remote transport will use the host1.example.com target from
        # inventory to proxy tasks execution on.
        run-on: host1.example.com
  # This will execute on localhost.
  - remote://my_aws_account
Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.