Nodes API


The /nodes endpoint in Chef Automate can be thought of as a sort of ‘logbook’ of the nodes in your infrastructure.

When a user creates a node, that node is added to the /nodes endpoint.

When a user adds a node integration, like aws or azure, nodes are added to the /nodes endpoint.

When an inspec report is ingested, a node is added to the /nodes endpoint. If it already exists, the last contact time is updated.

Node Status

All nodes have a status. Possible statuses are ‘unknown’, ‘reachable’, and ‘unreachable’. The default status is ‘unknown’.

Each time a user adds a manual node or a node integration, a detect job is executed on all the newly added nodes. This detect job attempts to connect to the node, via inspec, with inspec detect. If the detect job was successful, the status is updated from ‘unknown’ to ‘reachable’, and the platform information is updated (with the results of inspec detect).

If the detect job was not successful (the node could not be reached, for any reason), the status is updated to ‘unreachable’. Each time a scan job is executed on a node, the status of that node will be updated.

Node State

All nodes have a state. Possible states are unknown(“), ‘running’, ‘stopped’, and ‘terminated’. Default state is empty string (unknown).

For all nodes added via integrations, node state is updated on node addition and on polling interval.

If a node is found to have a state other than ‘running’, the node status is then also updated to ‘unreachable’.

Node state is updated to ‘running’ on report ingestion if the end time recorded by the inspec report is less than ten minutes from the ingestion time.

Filtering Nodes

The /nodes endpoint supports filtering by:

  • name
  • platform_name
  • platform_release
  • manager_type (‘automate’, ‘aws-ec2’, ‘aws-api’, …)
  • manager_id
  • account_id (the aws account id or azure tenant id)
  • region
  • source_id (a reference to the primary provider’s node)
  • state
  • statechange_timestamp
  • status
  • tags