Nodes endpoint

• 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"]

See the AST query language page.

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.

• latest_report_job_id (string): the job id associated with the latest report (not present if the run wasn't part of a job).

• ["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.

• expires_facts (boolean): indicates whether or not factsets for the node will be a candidate for expiration. This field will only be visible if the include_facts_expiration query parameter is set to true.

Note: configuration of fact expiration is an experimental feature which might be altered or removed in a future release, and for the time being, PuppetDB exports will not include this information.

• expires_facts_updated (timestamp or null): indicates when the value of expires_facts was last changed. This will be null if the value has never been explicitly set by a configure expiration command. This field will only be visible if the include_facts_expiration query parameter is set to true.

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>,
 "latest_report_job_id": <string or null>
}

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.

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]]]]]

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.

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>"}

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.

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.

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.)

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.

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.

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.