Connecting OpenBolt to OpenVoxDB
Configure OpenBolt to connect to OpenVoxDB.
OpenVoxDB authorization
OpenBolt authenticates with OpenVoxDB using an SSL client certificate. If OpenVoxDB is behind an API gateway that needs other credentials, such as an OAuth token, you can also add HTTP headers to OpenBolt’s requests.
Client certificate
Add the certname for the certificate you want to authenticate with
to /etc/puppetlabs/puppetdb/certificate-allowlist. This certificate has full
access to all OpenVoxDB API endpoints and can read all data, push new data, or
run commands on OpenVoxDB. 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
Configuration
To configure the OpenVoxDB client, add a puppetdb section to your OpenBolt
config with the following values:
| Option | Type | Description |
|---|---|---|
cacert |
String |
The path to the CA certificate for OpenVoxDB. |
connect_timeout |
Integer |
How long to wait in seconds when establishing connections with OpenVoxDB. |
headers |
Hash |
A map of HTTP headers to add to OpenVoxDB requests. |
read_timeout |
Integer |
How long to wait in seconds for a response from OpenVoxDB. |
server_urls |
Array |
An array of OpenVoxDB hosts to connect to, each including the https protocol and port (usually 8081), for example https://my-puppetdb-server.example.com:8081. OpenBolt tries each host until one connects. |
If you are using certificate authentication also set:
| Option | Type | Description |
|---|---|---|
cert |
String |
The path to the client certificate file to use for authentication. |
key |
String |
The private key for the certificate. |
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
To add custom headers, for example for an API gateway that requires an OAuth token:
puppetdb:
server_urls: ["https://puppet.example.com:8081"]
cacert: /etc/puppetlabs/puppet/ssl/certs/ca.pem
headers:
Authorization: "Bearer <token-content>"
Configuring multiple OpenVoxDB instances
The OpenVoxDB client supports connections to multiple OpenVoxDB instances. To
configure multiple OpenVoxDB instances, add the puppetdb-instances section to
your OpenBolt config.
The puppetdb-instances section is a map of configuration, where each key is the
name of the OpenVoxDB 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 a custom header:
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
headers:
Authorization: "Bearer <token-content>"
Connecting to a named OpenVoxDB instance
When using OpenBolt features that connect to OpenVoxDB, you can specify a named
instance to connect to if you have configured multiple OpenVoxDB instances
under the puppetdb-instances section.
To specify an OpenVoxDB instance to the puppetdb_* plan functions, pass the
OpenVoxDB instance name as the last positional argument to the function:
plan example() {
puppetdb_fact(['host.example.com'], 'instance-1')
}
To specify an OpenVoxDB instance to the apply plan function, use the _puppetdb
option:
plan example() {
apply('localhost', '_puppetdb' => 'instance-1') {
notice('Hello, world!')
}
}
To specify an OpenVoxDB instance to the puppetdb plugin, use the instance
option:
targets:
_plugin: puppetdb
query: "inventory[certname] { facts.osfamily = 'RedHat' }"
instance: instance-1
Specifying a default OpenVoxDB instance
When you do not specify a named OpenVoxDB instance, the OpenVoxDB client
connects to the default OpenVoxDB instance. Typically, this is the OpenVoxDB
instance configured under the puppetdb section.
For example, the following bolt-project.yaml configures a default
OpenVoxDB instance and two named OpenVoxDB instances:
puppetdb:
server_urls: ["https://puppetdb.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
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
headers:
Authorization: "Bearer <token-content>"
The following plan invokes the puppetdb_fact twice. The first invocation
connects to the default OpenVoxDB 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')
}
OpenBolt allows you to change the default OpenVoxDB instance to a named instance each time you run a command. This results in OpenBolt 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 OpenVoxDB instance
instance-1.
Testing
You can test your configuration with the following plan, which returns a list of all nodes in OpenVoxDB.
plan pdb_test {
return(puppetdb_query("nodes[certname] {}"))
}
Practical Usage
In practice, it is common to extract inventory from OpenVoxDB 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)
}