Connecting Bolt to PuppetDB

Bolt can authenticate with PuppetDB through an SSL client certificate or a PE RBAC token.

Add the certname for the certificate you want to authenticate with to /etc/puppetlabs/puppetdb/certificate-allowlist. This certificate has full access to all PuppetDB API endpoints and can read all data, push new data, or run commands on PuppetDB. To test the certificate you run the following curl command.

curl -X GET $SERVER_URL/pdb/query/v4 --data-urlencode 'query=nodes[certname] {}' --cert $CERT_PATH --key $KEY_PATH --cacert $CACERT_PATH

If you use Puppet Enterprise you can grant more restricted access to PuppetDB with a PE role-based access control (RBAC) token.

1. In PE, verify you are assigned to a role that has the appropriate RBAC permission. It needs the permission type Nodes and the action View node data from PuppetDB.

2. From the command line, run puppet-access login --lifetime <TIME PERIOD>.

3. When prompted, enter the same username and password that you use to log into the PE console. The token is generated and stored in a file for later use. The default location for storing the token is ~/.puppetlabs/token. 

4. Verify that authentication is working with the following curl command.

curl -X GET https://$SERVER_URL/pdb/query/v4 --data-urlencode 'query=nodes[certname] {}' -H "X-Authentication: `cat ~/.puppetlabs/token`" --cacert $CACERT_PATH

To configure the Bolt PuppetDB client, add a puppetdb section to your Bolt config with the following values:

If you are using certificate authentication also set:

If you are using a PE RBAC token set:

For example, to use certificate authentication:

puppetdb:
  server_urls: ["https://puppet.example.com:8081"]
  cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
  cert: /etc/puppetlabs/puppet/ssl/certs/my-host.example.com.pem
  key: /etc/puppetlabs/puppet/ssl/private_keys/my-host.example.com.pem

If PE is installed and PuppetDB is not defined in a config file, Bolt uses the PuppetDB config defined in either:

• $HOME/.puppetlabs/client-tools/puppetdb.conf or

• /etc/puppetlabs/client-tools/puppetdb.conf (Windows: %CSIDL_COMMON_APPDATA%\PuppetLabs\client-tools\puppetdb.conf).

Important: Bolt does not merge config files into a conf.d format the way that pe-client-tools does.

To use PE RBAC authentication:

puppetdb:
  server_urls: ["https://puppet.example.com:8081"]
  cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
  token: ~/.puppetlabs/token

The Bolt PuppetDB Client supports connections to multiple PuppetDB instances. To configure multiple PuppetDB instances, add the puppetdb-instances section to your Bolt config.

The puppetdb-instances section is a map of configuration, where each key is the name of the PuppetDB instance and values are the configuration for the instance. Each instance supports the same configuration as the puppetdb section.

For example, to configure a named instance that uses certificate authentication and a second instance that uses PE RBAC authentication:

puppetdb-instances:
  instance-1:
    server_urls: ["https://instance-1.example.com:8081"]
    cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
    cert: /etc/puppetlabs/puppet/ssl/certs/my-host.example.com.pem
    key: /etc/puppetlabs/puppet/ssl/private_keys/my-host.example.com.pem
  instance-2:
    server_urls: ["https://instance-2.example.com:8081"]
    cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
    token: ~/.puppetlabs/token

When using Bolt features that connect to PuppetDB, you can specify a named instance to connect to if you have configured multiple PuppetDB instances under the puppetdb-instances section.

To specify a PuppetDB instance to the puppetdb_* plan functions, pass the PuppetDB instance name as the last positional argument to the function:

plan example() {
  puppetdb_fact(['host.example.com'], 'instance-1')
}

To specify a PuppetDB instance to the apply plan function, use the _puppetdb option:

plan example() {
  apply('localhost', '_puppetdb' => 'instance-1') {
    notice('Hello, world!')
  }
}

To specify a PuppetDB instance to the puppetdb plugin, use the instance option:

targets:
  _plugin: puppetdb
  query: "inventory[certname] { facts.osfamily = 'RedHat' }"
  instance: instance-1

When you do not specify a named PuppetDB instance, the Bolt PuppetDB client connects to the default PuppetDB instance. Typically, this is the PuppetDB instance configured under the puppetdb section.

For example, the following bolt-project.yaml configures a default PuppetDB instance and two named PuppetDB instances:

puppetdb:
    server_urls: ["https://puppetdb.example.com:8081"]
    cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
    token: ~/.puppetlabs/token

puppetdb-instances:
  instance-1:
    server_urls: ["https://instance-1.example.com:8081"]
    cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
    cert: /etc/puppetlabs/puppet/ssl/certs/my-host.example.com.pem
    key: /etc/puppetlabs/puppet/ssl/private_keys/my-host.example.com.pem
  instance-2:
    server_urls: ["https://instance-2.example.com:8081"]
    cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
    token: ~/.puppetlabs/token

The following plan invokes the puppetdb_fact twice. The first invocation connects to the default PuppetDB instance (configured under the puppetdb section), while the second invocation connects to instance-2 (configured under the puppetdb-instances section).

plan example() {
  # Connects to https://puppetdb.example.com:8081
  puppetdb_fact(['host-1.example.com'])

  # Connects to https://instance-2.example.com:8081
  puppetdb_fact(['host-2.example.com'], 'instance-2')
}

Bolt allows you to change the default PuppetDB instance to a named instance each time you run a command. This results in Bolt connecting to the named instance whenever a named instance is not specified.

To specify a named instance as the default instance, use the puppetdb command-line option:

*nix shell command

$ bolt plan run example --puppetdb instance-1

PowerShell cmdlet

> Invoke-BoltPlan -Name example -PuppetDB instance-1

When running the example from above, the first invocation of the puppetdb_fact function will now connect to the named PuppetDB instance instance-1.

You can test your configuration with the following plan, which returns a list of all nodes in PuppetDB.

plan pdb_test {
  return(puppetdb_query("nodes[certname] {}"))
}

In practice, it is common to extract inventory from PuppetDB dynamically to use in a plan. The following is an example using the puppetdb_query() function directly. This method works but requires data munging to be effective.

plan puppetdb_query_targets {
  # query PuppetDB for a list of node certnames
  # this returns an array of objects, each object containing a "certname" parameter:
  # [ {"certname": "node1"}, {"certname": "node2"} ]
  $query_results = puppetdb_query("nodes[certname] {}")
  
  # since puppetdb_query() returns the JSON results from the API call, we need to transform this
  # data into Targets to use it in one of the run_*() functions.
  # extract the "certname" values, so now we have an array of hostnames
  $certnames = $query_results.map |$r| { $r['certname'] }
  
  # transform the arary of certnames into an array of Targets
  $targets = get_targets($certnames)
  
  # gather facts about all of the nodes
  run_task('facts', $targets)
}

Alternatively, the PuppetDB inventory plugin can be used to execute a query and return Targets. This avoids the data munging from the previous example:

plan puppetdb_plugin_targets {
  # Resolves "references" from the PuppetDB inventory plugin using the specified PQL query.
  $refs = {
    '_plugin' => 'puppetdb',
    'query'   => 'nodes[certname] {}',
  }
  $references = resolve_references($refs)
  
  # maps the results into a list of Target objects
  $targets = $references.map |$r| { Target.new($r) }
  
  # gather facts about all of the nodes
  run_task('facts', $targets)
}