PuppetDB stores and exposes a large amount of information. What can we do with it? Probably much more than what we might guess now. In this section, we explore in detail the REST endpoints available.
Diving into such details might be useful to better understand what can be queried and maybe trigger new ideas on what we can do with such information.
In these samples, we use curl with HTTP directly from the server where PuppetDB is installed.
Show all the facts of all our nodes (be careful, there may be a lot!):
curl 'http://localhost:8080/pdb/query/v4/facts'
Show the IP addresses of all our nodes (a similar search can be for any fact):
curl 'http://localhost:8080/pdb/query/v4/facts/ipaddress'
Show the node that has a specific IP address:
curl 'http://localhost:8080/pdb/query/v4/facts/ipaddress/10.42.42.27'
Show all the facts of a specific node:
curl -X GET http://localhost:8080/pdb/query/v4/facts --data-urlencode 'query=["=", "certname", "web01.example.com"]'
The response is always a JSON array with an entry per fact. Each entry is like the following:
{ "certname": <node name>, (IE: www01.example.com)
"name": <fact name>, (IE: operatingsystem)
"value": <fact value> (IE: ubuntu) }Show all the resources of type Mount for all the nodes:
curl 'http://localhost:8080/pdb/query/v4/resources/Mount'
Note that the resource type must be capitalized, as we are referring to the type, and not to an specific instance.
Show all the resources of a given node:
curl -X GET http://localhost:8080/pdb/query/v4/resources --data-urlencode
'query=["=", "certname", "web01.example.com"]'Show all nodes that have Service['apache'] with ensure = running:
curl -X GET http://localhost:8080/pdb/query/v4/resources/Service
--data-urlencode 'query=[ "and" , ["=", "title", "apache" ],
["=", ["parameter", "ensure"], "running"] ]'Same as before, using a different approach:
curl -X GET http://localhost:8080/pdb/query/v4/resources/Service/apache
--data-urlencode 'query=["=", ["parameter", "ensure"], "running"]'Show all the resources managed for a given node in a given manifest:
curl -X GET http://localhost:8080/pdb/query/v4/resources/ --data-urlencode
'query=["and" ["=", "file", "/etc/puppet/manifests/apache.pp"],
["=", "certname", "web01.example.com"]]'
The response format of the resources endpoint shows how we can query everything about the resources managed by Puppet and defined in our manifests:
{"certname": "<node name>", (IE: www01.example.com)
"resource": "<the resource's unique hash>", (IE: f3h34ds...)
"type": "<resource type>", (IE: Service)
"title": "<resource title>", (IE: apache)
"exported": "<true|false>", (IE: false)
"tags": ["<tag>", "<tag>"], (IE: "apache", "class" ...)
"file": "<manifest path>", (IE: "/etc/puppet/manifests/site.pp")
"line": "<manifest line>", (IE: "3")
"parameters": {<parameter>: <value>, (IE: "enable" : true,)
<parameter>: <value>,
...}}Show all the (not deactivated) nodes:
curl 'http://localhost:8080/pdb/query/v4/nodes'
Show all the facts of a specific node (this is a better alternative than the earlier example):
curl 'http://localhost:8080/pdb/query/v4/nodes/www01.example.com/facts'
Show all the resources of a specific node (this is a better alternative than the earlier example):
curl 'http://localhost:8080/pdb/query/v4/nodes/www01.example.com/resources'
Show all the nodes with the operating system CentOS:
curl -X GET http://localhost:8080/pdb/query/v4/nodes --data-urlencode 'query=["=", ["fact","operatingsystem"], "CentOS"]'
The response format is as follows:
{"certname": <string>,
"deactivated": <timestamp or null>,
"expired": <timestamp or null>,
"catalog_timestamp": <timestamp or null>,
"facts_timestamp": <timestamp or null>,
"report_timestamp": <timestamp or null>,
"catalog_environment": <string or null>,
"facts_environment": <string or null>,
"report_environment": <string or null>,
"latest_report_status": <string>,
"latest_report_hash": <string>
}When using the facts and resources sub URLs, we get replies in the same format as the relative endpoint.
Get the whole catalog (the last saved one) of a node (all the resources and edges):
curl 'http://localhost:8080/pdb/query/v4/catalogs/www01.example.com'
Get the names (just the names, not the values) of all the stored facts:
curl 'http://localhost:8080/pdb/query/v4/fact-names'
These are mostly useful to check PuppetDB performances and operational statistics. Some of them are visible from the performance dashboard.
Get the names of all the metrics available:
curl 'http://localhost:8080/metrics/v1/mbeans'
The result shows a remarkable list of items in JMX Mbean ObjectName style:
<Mbean-doman>:type=<Type>[,name:<Name>]
An example, in URL-encoded format as returned by PuppetDB, is as follows:
"com.jolbox.bonecp:type=BoneCP" : "/metrics/mbean/com.jolbox.bonecp%3Atype%3DBoneCP"
Available metrics are about nodes' population, database connection, delivery status of the processed commands, HTTP access hits, command processing, HTTP access, storage operations, JVM statistics, and the message queue system.
The following are few examples.
The total number of nodes in the population:
curl http://localhost:8080/metrics/v1/mbeans/com.puppetlabs.puppetdb.query.population%3Atype%3Ddefault%2Cname%3Dnum-nodes
The average number of resources per node:
curl http://localhost:8080/metrics/v1/mbeans/com.puppetlabs.puppetdb.query.population%3Atype%3Ddefault%2Cname%3Davg-resources-per-node
Statistics about the time used for the command replace-catalog:
curl http://localhost:8080/ metrics/mbeans/com.puppetlabs.puppetdb.scf.storage%3Atype%3Ddefault%2Cname%3Dreplace-catalog-time
Show the summaries of all the saved reports of a given node:
curl -X GET http://localhost:8080/pdb/query/v4/reports --data-urlencode 'query=["=", "certname", "db.example.com"]'
Search all reports for failures:
curl -X GET 'http://localhost:8080/pdb/query/v4/events' --data-urlencode
'query=["=", "status" , "failure"]'
Search all reports for failures on Service type:
curl -X GET 'http://localhost:8080/pdb/query/v4/events' --data-urlencode
'query=[ "and", ["=", "status" , "failure"],
["=", "resource-type", "Service"] ]'
Search all reports for any change to the file with title hosts:
curl -X GET 'http://localhost:8080/pdb/query/v4/events' --data-urlencode
'query=[ "and", ["=", "resource-type", "File"],
["=", "resource-title", "hosts" ] ]'
Search all reports for changes in the content of the file with title hosts:
curl -X GET 'http://localhost:8080/pdb/query/v4/events' --data-urlencode
'query=[ "and", ["=", "resource-type", "File"],
["=", "resource-title", "hosts" ],
["=", "property", "content"] ]'
Show changes to the specified file only after a given timestamp:
curl -X GET 'http://localhost:8080/pdb/query/v4/events' --data-urlencode
'query=[ "and", ["=", "resource-type", "File"],
["=", "resource-title", "hosts" ],
[">", "timestamp", "2015-12-18T14:00:00"] ]'
Show all changes in a timestamp range:
curl -X GET 'http://localhost:8080/pdb/query/v4/events' --data-urlencode
'query=[ "and", [">", "timestamp", "2015-12-18T14:00:00"] ,
["<", "timestamp","2015-12-18T15:00:00"] ]'
Show all the changes related to resources provided by a specific manifest file:
curl -X GET 'http://localhost:8080/pdb/query/v4/events' --data-urlencode
'query=["=","file","/etc/puppet/modules/hosts/manifests/init.pp"]'
Show the count of resources of type Service, summarized per resource:
curl -X GET 'http://localhost:8080/pdb/query/v4/event-counts'
--data-urlencode 'query=["=", "resource-type", "Service" ]'
--data-urlencode 'summarize-by=resource'
Show the count of resources of type Package, summarized per node name:
curl -X GET 'http://localhost:8080/pdb/query/v4/event-counts'
--data-urlencode 'query=["=", "resource-type", "Package" ]'
--data-urlencode 'summarize-by=certname'
Show the aggregated count of events for a node:
curl -G 'http://localhost:8080/pdb/query/v4/aggregate-event-counts'
--data-urlencode 'query=["=", "certname", "db.example.com"]'
--data-urlencode 'summarize-by=containing-class'
Show the aggregated count for all events on services on any node:
curl -G 'http://localhost:8080/pdb/query/v4/aggregate-event-counts'
--data-urlencode 'query=["=", "resource-type", "Service"]'
--data-urlencode 'summarize-by=certname'