PuppetDB 1.5 » API » Query » Curl Tips

Included in Puppet Enterprise 3.2. A newer version is available; see the version menu above for details.

You can use curl to directly interact with PuppetDB’s REST API. This is useful for testing, prototyping, and quickly fetching arbitrary data.

The instructions below are simplified. For full usage details, see the curl manpage . For additional examples, please see the docs for the individual REST endpoints:

Using curl From localhost (Non-SSL/HTTP)

With its default settings, PuppetDB accepts unsecured HTTP connections at port 8080 on localhost. This allows you to SSH into the PuppetDB server and run curl commands without specifying certificate information:

curl 'http://localhost:8080/v3/facts/<node>'
curl 'http://localhost:8080/v3/metrics/mbean/java.lang:type=Memory'

If you have allowed unsecured access to other hosts in order to monitor the dashboard, these hosts can also use plain HTTP curl commands.

Using curl From Remote Hosts (SSL/HTTPS)

To make secured requests from other hosts, you will need to supply the following via the command line:

  • Your site’s CA certificate (--cacert)
  • An SSL certificate signed by your site’s Puppet CA (--cert)
  • The private key for that certificate (--key)

Any node managed by puppet agent will already have all of these and you can re-use them for contacting PuppetDB. You can also generate a new cert on the CA puppet master with the puppet cert generate command.

Note: If you have turned on certificate whitelisting, you must make sure to authorize the certificate you are using.

curl 'https://<your.puppetdb.server>:8081/v3/facts/<node>' --cacert /etc/puppet/ssl/certs/ca.pem --cert /etc/puppet/ssl/certs/<node>.pem --key /etc/puppet/ssl/private_keys/<node>.pem

Locating Puppet Certificate Files

Locate Puppet’s ssldir as follows:

$ sudo puppet config print ssldir

Within this directory:

  • The CA certificate is found at certs/ca.pem
  • The corresponding private key is found at private_keys/<name>.pem
  • Other certificates are found at certs/<name>.pem

Dealing with complex query strings

Many query strings will contain characters like [ and ], which must be URL-encoded. To handle this, you can use curl’s --data-urlencode option.

If you do this with an endpoint that accepts GET requests, you must also use the -G or --get option. This is because curl defaults to POST requests when the --data-urlencode option is present.

curl -G 'http://localhost:8080/v3/nodes' --data-urlencode 'query=["=", ["node", "active"], true]'

↑ Back to top