Inventory endpoints

Use the inventory endpoints to check whether the orchestrator can reach a node.

These endpoints are based on nodes being connected to the Puppet Communications Protocol (PCP) broker, which is part of the Puppet orchestrator architecture.

GET /inventory

Retrieve a list of all nodes connected to the Puppet Communications Protocol (PCP) broker.

Request format

When Forming orchestrator API requests to this endpoint, the request is a basic call, such as:
GET https://orchestrator.example.com:8143/orchestrator/v1/inventory

The GET /inventory endpoint does not support any parameters; however, as with other orchestrator API endpoints, you must provide authentication.

Response format

A successful response is a JSON object containing an array of nodes. The response uses the following keys to provide information about each node's PCP broker connection:
Key Definition
name The node's name.
connected The status of the connection between the node and the PCP broker, either true (connected) or false (disconnected).
broker The PCP broker the node is connected to. If connected is false, this key is empty or omitted.
timestamp The time when the node connected to the PCP broker. If connected is false, this key is empty or omitted.
For example, this response provides details about three nodes, one of which is currently disconnected:
{
  "items" : [
    {
      "name" : "node1.example.com",
      "connected" : true,
      "broker" : "pcp://broker1.example.com/server",
      "timestamp": "2016-010-22T13:36:41.449Z"
    },
    {
      "name" : "node2.example.com",
      "connected" : true,
      "broker" : "pcp://broker2.example.com/server",
      "timestamp" : "2016-010-22T13:39:16.377Z"
    },
    {
      "name" : "node3.example.com",
      "connected" : false
    }
  ]
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 500 response if the PCP broker can't be reached.

GET /inventory/<node>

Retrieve information about a single node's connection to the Puppet Communications Protocol (PCP) broker.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include a specific node name, such as:
GET "https://orchestrator.example.com:8143/orchestrator/v1/inventory/<NODE_NAME>"
If you do not know the node's name, you can use the GET /inventory endpoint to query all nodes. If you want to query multiple specific nodes at once, use POST /inventory.

The GET /inventory/<node> endpoint does not support any additional parameters; however, as with other orchestrator API endpoints, you must provide authentication.

Response format

A successful response is a JSON object that uses these keys to provide information about the specified node's PCP broker connection:
Key Definition
name The node's name.
connected The status of the connection between the node and the PCP broker, either true (connected) or false (disconnected).
broker The PCP broker the node is connected to. If connected is false, this key is empty or omitted.
timestamp The time when the node connected to the PCP broker. If connected is false, this key is empty or omitted.

For example:

{
  "name" : "node1.example.com",
  "connected" : true,
  "broker" : "pcp://broker.example.com/server",
  "timestamp" : "2017-03-29T21:48:09.633Z"
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 500 response if the PCP broker can't be reached.

POST /inventory

Returns information about multiple nodes' connections to the Puppet Communications Protocol (PCP) broker.

Request format

When Forming orchestrator API requests to this endpoint, the content type is application/json. The body must be a JSON object specifying an array node names, such as:
{
  "nodes" : [
    "node1.example.com",
    "node2.example.com",
    "node3.example.com"
  ]
}
A complete curl request using this body might look like:
type_header='Content-Type: application/json'
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/inventory"
data='{"nodes" : [ "node1.example.com", "node2.example.com", "node3.example.com"]}'

curl --insecure --header "$type_header" --header "$auth_header" --request POST "$uri" --data "$data"

Response format

A successful response is a JSON object that uses these keys to provide information about each node's PCP broker connection:
Key Definition
name The node's name.
connected The status of the connection between the node and the PCP broker, either true (connected) or false (disconnected).
broker The PCP broker the node is connected to. If connected is false, this key is empty or omitted.
timestamp The time when the node connected to the PCP broker. If connected is false, this key is empty or omitted.
For example, this is a response to a query about three specific nodes:
{
  "items" : [
    {
      "name" : "node1.example.com",
      "connected" : true,
      "broker" : "pcp://broker.example.com/server",
      "timestamp" : "2017-07-14T15:57:33.640Z"
    },
    {
      "name" : "node2.example.com",
      "connected" : false
    },
    {
      "name" : "node3.example.com",
      "connected" : true,
      "broker" : "pcp://broker.example.com/server",
      "timestamp" : "2017-07-14T15:41:19.242Z"
    }
  ]
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 500 response if the PCP broker can't be reached.