API Concept in PuppetDB

 API query

The API query is executed using the curl command from the command line. In order to run a query, you must send an HTTP GET or POST request to an endpoint URL. 

You have to specify a query URL argument (for GET requests) or a JSON-valued payload (for POST requests). The format of the results is application/json.

Let's have a look at the API queries:

Querying With CURL

You can execute API queries with curl with SSL or without SSL. It is preferred to use SSL in your database. This will reduce the risk of data loss. Let's have a look over the commands.

Without SSL command:

curl -X GET http://puppetdb.example.com:8080/pdb/query/v4/resources \
  --data-urlencode query@<FILENAME>

curl -X POST http://puppetdb.example.com:8080/pdb/query/v4/resources \
  -H 'Content-Type:application/json'
  -d '{"query":["=","certname","codingninjas.com"]}'

 

You must provide a private key, a CA certificate, and a certificate to execute the command. The <FILENAME> is the file that contains the API queries.

With SSL command:

curl -X GET https://puppetdb.example.com:8081/pdb/query/v4/resources \
  --tlsv1 \
  --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \
  --cert /etc/puppetlabs/puppet/ssl/certs/thisnode.pem \
  --key /etc/puppetlabs/puppet/ssl/private_keys/thisnode.pem \
  --data-urlencode query@<FILENAME>

 

You must provide a private key, a CA certificate, and a certificate to execute the command. The FILENAME is the file that contains the API queries.

Querying With Puppet Code

The puppetdb_query function is used to query PuppetDB from a Puppet manifest.

Command:

$debian_nodes_query = '["from", "nodes", ["=", ["fact", "operating system"], "Debian"]]'
$debian_nodes = puppetdb_query($debian_nodes_query).each |$value| { $value["certname"] }
Notify {"Debian nodes":
    message => "Your debian nodes are ${join($debian_nodes, ', ')}",
}

The above command uses puppetdb_query function. This function is present in PuppetDB terminus. You can directly use this function specifying your query.

API Curl

The curl command is used to communicate directly with PuppetDB's REST API. It is helpful for prototyping, testing, and fast retrieving data.

Using Curl from localhost

PuppetDB accepts unsecured HTTP connections at port 8080 by default. This enables you to conduct curl and SSH commands into the PuppetDB server without providing any certificate information.

Command:

curl http://localhost:8080/pdb/query/v4/nodes
curl 'http://localhost:8080/metrics/v1/mbeans/java.lang:type=Memory'

 

The above command executes without specifying the certificate information. 

Using curl from remote host

You can use the curl command from the remote host using the following ways:

• Using a pair of private keys.
   
• Using an RBAC token. 
   
• Locating Puppet certificate files.
   

Let's look at the details of them.

Using a pair of private keys

The private keys provide the security during API query. You must enter the following attributes via the command line to send secured requests to other hosts:

• The CA certificate for your website (—cacert)
   
• An SSL certificate issued by the Puppet CA for your website (—cert)
   
• The certificate's private key (—key)

All the attributes are already present on any node controlled by a Puppet agent. They are used to connect to PuppetDB.

Command:

curl 'https://<your.puppetdb.server>:8081/pdb/query/v4/nodes' \
  --tlsv1 \
  --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \
  --cert /etc/puppetlabs/puppet/ssl/certs/<node>.pem \
  --key /etc/puppetlabs/puppet/ssl/private_keys/<node>.pem

 

Using an RBAC token 

The Role Based Access Control also provides security during API query.

• The CA certificate for your website (—cacert)
   
• An RBAC token with required permissions.
   

The CA certificate is by default included in the PuppetDB node.

Command:

curl 'https://<your.puppetdb.server>:8081/pdb/query/v4/nodes' \
  -H "X-Authentication: <token contents>" \
  --tlsv1 \
  --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem

You have to specify your RBAC token in the <token contents>

Locating Puppet certificate files

You can locate the Puppet certificate files using the following command:

sudo puppet config print ssldir

The CA certificate is present at certs/ca.pem

The private key is present at private_keys/<name>.pem

Other certificates are present at certs/<name>.pem

Dealing with Complex Query Strings

You can include multiple queries in your curl command. All the queries are included between the [ and ] characters.

You must additionally use the -G or —get the option if you're using an endpoint that supports GET requests. In the absence of the —data-urlencode option, curl defaults to POST requests.

Command:

curl -G http://localhost:8080/pdb/query/v4/nodes \
  --data-urlencode 'query=["=", "node_state", "active"]'

Pretty querying of PuppetDB

PuppetDB returns the result of the query in JSON format. This contains the result in an unstructured manner. You can structure your result in PuppetDB using pretty parameter. This parameter takes a boolean value (True/false). Set the parameter value to true.

Command:

curl -X GET http://localhost:8080/pdb/query/v4/nodes \
    --data-urlencode 'pretty=true'

This command will return the result in a structured manner.

Querying PuppetDB with POST

You can query in PuppetDB using the POST method. This method is useful for large queries. We can also limit our queries using this method. Let's have a look at the example:

Command:

curl -X POST http://localhost:8080/pdb/query/v4/nodes \
  -H 'Content-Type:application/json' \
  -d '{"query":["~","certificatename",".*.com"],"order_by":[{"field":"certificatename"}],"limit":5}'

 

This command will limit our query to 5 entries. 

Querying PuppetDB based on specific resource attributes

The POST method is also used to query on specific resource attributes.

Example:

resources {
  tag = "codingninjas" and
  exported = true
} 

This is our resource attribute.

Command:

curl -X POST http://localhost:8080/pdb/query/v4 \
  -H 'Content-Type:application/json' \
  -d '{"query": "resources { tag = \"codingninjas\" and exported = true }"}'

This command will give the result of resources having 'codingninjas 'as their tag.

Frequently Asked Questions

What is PuppetDB?

PuppetDB is a fast, highly scalable, and reliable database for Puppet.

Which databases are supported in PuppetDB?

PostgreSQL is the recommended database for using PuppetDB.

Is Puppet compatible with windows?

Yes, Puppet is compatible with all versions of the Windows operating system.

Conclusion

In this article, we have discussed the details of the API Concept in PuppetDB along with the details of API query and API curl.

We hope that the blog has helped you enhance your knowledge regarding API Concept in PuppetDB. You can refer to our guided paths on the Coding Ninjas Studio platform to learn more about DSA, DBMS, Competitive Programming, Python, Java, JavaScript, etc. To practice and improve yourself in the interview, you can also check out Top 100 SQL problems, Interview experience, Coding interview questions, and the Ultimate guide path for interviews. Do upvote our blogs to help other ninjas grow. Happy Coding!!