Skip to main content

Nodes API

Nodes

The /nodes endpoint in Chef Automate is something of a ’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 a Chef InSpec report or a Chef Infra Client run is ingested, a node is added to the /nodes endpoint. If the node already exists, its last contact time, run data, and scan data are updated. When run data and scan data are updated, the latest information is stored for the run id or report id, the status, and the penultimate status.

Node Status

All nodes have one of three possible statuses: ‘unknown’, ‘reachable’, and ‘unreachable’. The default status is ‘unknown’.

Each time a user adds one or more nodes manually or with a node integration (AWS, Azure, or GCP), Chef Automate runs aninspec detect job on the newly added nodes. If the detect job is successful, the node status updates from ‘unknown’ to ‘reachable’, and the platform information is updated from the inspec detect results. If the detect job is unsuccessful, meaning the node couldn’t be reached, the node’s status updates to ‘unreachable’. The status updates every time a scan job runs on the node.

Node State

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

For all nodes added through integrations, node state is updated both when nodes are added and on a scheduled 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_timerange (supports two timestamps of type “2019-03-05T00:00:00Z”)
  • status
  • tags
  • last_run_timerange (last time reported on ingested Chef Infra Client run: supports two timestamps of type “2019-03-05T00:00:00Z” (RFC3339))
  • last_scan_timerange (last time reported on ingested scan: supports two timestamps of type “2019-03-05T00:00:00Z” (RFC3339))
  • last_run_status (status on last ingested Chef Infra Client run)
  • last_scan_status (status on last ingested scan)
  • last_run_penultimate_status (status on second to last ingested Chef Infra Client run)
  • last_scan_penultimate_status (status on second to last ingested scan)

Examples

  • Show me all nodes whose last scan had a status of failed and a penultimate status of passed

or in other words, which nodes were previously passing their scans and just started failing?

sample request:

curl -s --insecure -H "api-token: $token_val"
https://a2-dev.test/api/v0/nodes/search -d '{
  "filters": [
    {"key": "last_scan_status", "values": ["FAILED"]},
    {"key": "last_scan_penultimate_status", "values": ["PASSED"]}
  ]
}'

sample truncated response:

{"nodes":[{"id":"0e05fcf2-2fab-36ee-bb84-5b7d5888c33a","name":"chef-load-blue-delladonna-indigo","platform":"debian","platform_version":"8.11","last_contact":"2019-05-14T18:08:43Z","run_data":{"id":"","status":"UNKNOWN","penultimate_status":"UNKNOWN","end_time":null},"scan_data":{"id":"5640fbb7-d1ba-4c67-b0cd-9db4fcfc2598","status":"FAILED","penultimate_status":"PASSED","end_time":"2019-05-14T18:08:43Z"}}]}
  • Show me all nodes whose last Chef Infra Client run passed and last scan failed, that had a penultimate Chef Infra Client run status of failed

or in other words, which nodes just started passing their Chef Infra Client runs but are failing their scans?

sample request:

curl -s --insecure -H "api-token: $token_val"
https://a2-dev.test/api/v0/nodes/search -d '{
  "filters": [
    {"key": "last_run_status", "values": ["PASSED"]},
    {"key": "last_scan_status", "values": ["FAILED"]},
    {"key": "last_run_penultimate_status", "values": ["FAILED"]}
  ]
}'
  • Show me all nodes that had a last scan ingested sometime in the last 48 hours with a status of failed

or in other words, which nodes that were ingested in the last 48 hours failed their scans?

sample request:

curl -s --insecure -H "api-token: $token_val"
https://a2-dev.test/api/v0/nodes/search -d '{
  "filters": [
    {"key": "last_scan_status", "values": ["FAILED"]},
    {"key": "last_scan_timerange", "values": ["2019-05-12T00:00:00Z", "2019-05-16T00:00:00Z" ]}
  ]
}'
  • Show me all nodes tagged with deployment:staging OR deployment:test. We OR between multiple values of the same key

sample request:

curl -s --insecure -H "api-token: $token_val"
https://a2-dev.test/api/v0/nodes/search -d '{
 "filters": [
   {"key": "deployment", "values": ["staging", "test"]}
 ]
}'
  • Show me all nodes tagged with deployment:prod AND org:marketing. We AND between different tag key filters

sample request:

curl -s --insecure -H "api-token: $token_val"
https://a2-dev.test/api/v0/nodes/search -d '{
 "filters": [
   {"key": "deployment", "values": ["prod"]},
   {"key": "org", "values": ["marketing"]}
 ]
}'

Bulk Node Add

Use the nodes/bulk-create endpoint to add multiple nodes that share the same tags and credentials. The endpoint accepts an array of node objects. If you specify a name_prefix, Chef Automate generates a node name by combining the prefix and the host value, resulting in a name like prefix-host. Any tags you specify are applied to each node in the request.

curl -s --insecure -H "api-token: $token_val" https://a2-dev.test/api/v0/nodes/bulk-create -d '
{"nodes": [{
     "name_prefix": "my-ssh-node",
     "manager":"automate",
     "target_config": {
        "backend":"ssh",
        "hosts":["localhost","127.0.0.1"],
        "secrets":["2998c3a1-d596-43d4-b2b3-4837a46cee19"],
        "port": 22
      },
      "tags": [
        { "key":"test-node", "value":"is-amazing" },
        { "key":"compliance-service", "value":"rockin-like-whoa" },
        { "key":"_no_auto_detect", "value":"true" }
      ]
    },
    {
     "name": "my-other-node",
     "manager":"automate",
      "target_config": {
        "backend":"ssh",
        "hosts":["localhost"],
        "secrets":["2998c3a1-d596-43d4-b2b3-4837a46cee19"],
        "port": 22
      },
      "tags": [
        { "key":"test-node", "value":"is-more-amazing" }
      ]
    }
  ]
}'

Bulk Node Delete

The /nodes/delete endpoint allows users to bulk-delete nodes based on a query. To examine the outcome of this destructive action before running it, test the query first on the api/v0/nodes/search endpoint.

curl -s --insecure -H "api-token: $token_val"
https://a2-dev.test/api/v0/nodes/delete -d '{
  "filters": [
    {"key": "name", "values": ["vj*"]}
  ]
}'

Thank you for your feedback!

×