PuppetDB 5.0: Nodes endpoint

This version of PuppetDB is not included in Puppet Enterprise. The latest version of PE includes PuppetDB 4.4. A newer version is available; see the version menu above for details.

Nodes can be queried by making an HTTP request to the /nodes endpoint.

/pdb/query/v4/nodes

This will return all nodes matching the given query. Deactivated and expired nodes aren’t included in the response.

URL parameters

  • query: optional. A JSON array of query predicates, in prefix notation (["<OPERATOR>", "<FIELD>", "<VALUE>"]). See the sections below for the supported operators and fields. For general info about queries, see our guide to query structure.

To query for the latest fact/catalog/report timestamp submitted by ‘example.local’, the JSON query structure would be:

["=", "certname", "example.local"]

Query operators

See the AST query language page.

Query fields

The below fields are allowed as filter criteria and are returned in all responses.

  • certname (string): the name of the node that the report was received from.

  • catalog_environment (string): the environment for the last received catalog.

  • facts_environment (string): the environment for the last received fact set.

  • report_environment (string): the environment for the last received report.

  • catalog_timestamp (timestamp): the last time a catalog was received. Timestamps are always ISO-8601 compatible date/time strings.

  • facts_timestamp (timestamp): the last time a fact set was received. Timestamps are always ISO-8601 compatible date/time strings.

  • report_timestamp (timestamp): the last time a report run was complete. Timestamps are always ISO-8601 compatible date/time strings.

  • latest_report_status (string): the status of the latest report. Possible values come from Puppet’s report status, which can be found here.

  • latest_report_noop (boolean): indicates whether the most recent report for the node was a noop run.

  • latest_report_noop_pending (boolean): indicates whether the most recent report for the node contained noop events.

  • latest_report_corrective_change (boolean): a flag indicating whether the latest report for the node included events that remediated configuration drift. This field is only populated in PE.

  • cached_catalog_status (string): Cached catalog status of the last puppet run for the node. Possible values are explicitly_requested, on_failure, not_used or null.

  • latest_report_hash (string): a hash of the latest report for the node.

  • ["fact", <FACT NAME>] (string, number, Boolean): the value of <FACT NAME> for a node. Inequality operators are allowed, and will skip non-numeric values.

    Note that nodes which are missing a fact referenced by a not query will match the query.

Response format

The response is a JSON array of hashes, where each hash has the form:

{
 "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_noop": <boolean>,
 "latest_report_noop_pending": <boolean>,
 "latest_report_hash": <string>
}

At least one of the _timestamp fields will be non-null.

The array is unsorted.

If no nodes match the query, an empty JSON array will be returned.

Examples

You can use curl to query information about nodes:

curl http://localhost:8080/pdb/query/v4/nodes

This query will return nodes whose kernel is Linux and whose uptime is less than 30 days:

["and",
  ["=", ["fact", "kernel"], "Linux"],
  [">", ["fact", "uptime_days"], 30]]

This query will return node counts for each distinct facts_environment among active nodes:

["extract", [["function","count"],"facts_environment"],
  ["null?", "deactivated", true],
  ["group_by", "facts_environment"]]

This query, which includes a subquery against the fact-contents endpoint, will return all nodes with at least 10 days of uptime:

["in", "certname",
  ["extract", "certname",
    ["select_fact_contents",
      ["and", ["=", "path", ["system_uptime", "days"]],
              [">=", "value", 10]]]]]

/pdb/query/v4/nodes/<NODE>

This will return status information for the given node, active or not. It behaves exactly like a call to /pdb/query/v4/nodes with a query string of ["=", "certname", "<NODE>"].

curl -X GET http://localhost:8080/pdb/query/v4/nodes/mbp.local
{
    "deactivated" : null,
    "facts_environment" : "production",
    "report_environment" : "production",
    "catalog_environment" : "production",
    "facts_timestamp" : "2015-06-19T23:03:42.401Z",
    "expired" : null,
    "report_timestamp" : "2015-06-19T23:03:37.709Z",
    "certname" : "mbp.local",
    "catalog_timestamp" : "2015-06-19T23:03:43.007Z",
    "latest_report_status": "success",
    "latest_report_noop": false,
    "latest_report_noop_pending": true,
    "latest_report_hash": "2625d1b601e98ed1e281ccd79ca8d16b9f74fea6"
}

URL parameters / query operators / query fields

This route is an extension of the plain nodes endpoint. It uses the same parameters, operators, and fields.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

Response format

The response is a single hash in the same form used for the plain nodes endpoint shown above.

If a node of that certname doesn’t exist, the response will instead be a hash of the form:

{"error": "No information is known about <NODE>"}

/pdb/query/v4/nodes/<NODE>/facts

This will return the facts for the given node. Facts from deactivated and expired nodes aren’t included in the response.

This is a shortcut to the /pdb/query/v4/facts endpoint. It behaves the same as a call to /pdb/query/v4/facts with a query string of ["=", "certname", "<NODE>"].

URL parameters / query operators / query fields / response format

This route is an extension of the facts endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

/pdb/query/v4/nodes/<NODE>/facts/<NAME>

This will return facts with the given name for the given node. Facts from deactivated and expired nodes aren’t included in the response.

This is a shortcut to the /pdb/query/v4/facts endpoint. It behaves the same as a call to /pdb/query/v4/facts with a query string of:

["and",
    ["=", "certname", "<NODE>"],
    ["=", "name", "<NAME>"]]

URL parameters / query operators / query fields / response format

This route is an extension of the facts endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

/pdb/query/v4/nodes/<NODE>/facts/<NAME>/<VALUE>

This will return facts with the given name and value for the given node. Facts from deactivated and expired nodes aren’t included in the response.

This is a shortcut to the /pdb/query/v4/facts endpoint. It behaves the same as a call to /pdb/query/v4/facts with a query string of:

["and",
    ["=", "certname", "<NODE>"],
    ["=", "name", "<NAME>"],
    ["=", "value", "<VALUE>"]]

URL parameters / query operators / query fields / response format

This route is an extension of the facts endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

(However, for this particular route, there aren’t any practical criteria left.)

/pdb/query/v4/nodes/<NODE>/resources

This will return the resources for the given node. Resources from deactivated and expired nodes aren’t included in the response.

This is a shortcut to the /pdb/query/v4/resources route. It behaves the same as a call to /pdb/query/v4/resources with a query string of ["=", "certname", "<NODE>"].

URL parameters / query operators / query fields / response format

This route is an extension of the resources endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

/pdb/query/v4/nodes/<NODE>/resources/<TYPE>

This will return the resources of the indicated type for the given node. Resources from deactivated and expired nodes aren’t included in the response.

This is a shortcut to the /pdb/query/v4/resources/<TYPE> route. It behaves the same as a call to /pdb/query/v4/resources with a query string of:

["and",
    ["=", "certname", "<NODE>"],
    ["=", "type", "<TYPE>"]]

URL parameters / query operators / query fields / response format

This route is an extension of the resources endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

/pdb/query/v4/nodes/<NODE>/resources/<TYPE>/<TITLE>

This will return the resource of the indicated type and title for the given node. Resources from deactivated and expired nodes aren’t included in the response.

This is a shortcut to the /pdb/query/v4/resources/<TYPE>/<TITLE> route. It behaves the same as a call to /pdb/query/v4/resources with a query string of:

["and",
    ["=", "certname", "<NODE>"],
    ["=", "type", "<TYPE>"],
    ["=", "title", "<TITLE>"]]

URL parameters / query operators / query fields / response format

This route is an extension of the resources endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.

Paging

This query endpoint supports paged results via the common PuppetDB paging URL parameters. For more information, please see the documentation on paging.

↑ Back to top