Client Runs

Overview

The client runs page shows all nodes that have been connected to Chef Automate either directly or via a Chef Server proxy. A node will not show up on this screen until a chef-client run has been executed.

Chef Client Run Status Overview

This chart displays a summation of node statuses of failed, missing or successful and a total node count. This chart will update based on the filters applied.

Client Runs Overview

Node List Table

The node list table contains a list of Automate connected nodes. Filter the node list table by selecting any of the status tabs below the Chef Client Run Status box. Sort the nodes listed on the table by selecting the arrows to the right of the column headers: Node Name, Check-In, Uptime, Platform, Environment or Policy Group. Selecting an entry in this table will take you to a Node details page with more information about the chef-client runs associated with this node.

It is possible for a node to be present in this table without any associated run history. This happens when data retention settings erase the most recent run history for that node. When this happens, a no data icon appears and you will be unable to view any node details. The node will stay in this table as a missing node until it is deleted from Automate. Nodes that are deleted using Chef Server will automatically be deleted from Automate.

Filtering

The search bar enables you to filter nodes based on a set of criteria. More than one filter can be applied and will be treated as a requirement. A node must have each of the filters applied in order to be shown. In order to apply a filter, select the filter category and begin typing to display autocomplete options. Save a search by clicking on the share button to the right of the search bar, which shows a url that can be copied and shared.

The following is a list of search bar categories:

  • Cookbook - A cookbook name.
  • Recipe - A recipe within a cookbook.
  • Resource Name - A resource within a cookbook.
  • Environment - Nodes can have one environment.
  • Role - Search by nodes assigned to a role. Nodes can have zero or many roles.
  • Node Name - Name of the node.
  • Platform - OS Platform of a node.
  • Attribute - Search for an attribute key, this will not search across attribute values.
  • Policy Name - Name of the policy as set in policyfile.rb, only nodes using policyfiles will be shown.
  • Policy Revision - The policy revision ID, only nodes using policyfiles will be shown.
  • Policy Group - Policy group name, only nodes using policyfiles will be shown.

See more about policyfiles.

To filter nodes by Chef Server or Chef Server organization use the filters available in the sidebar on the left hand side. The sidebar shows all Chef Servers and all available Chef Server organizations.

Node details

Clicking on a node in the node list table takes you to the node details page, which displays the most recent converge results. To look at historical run data, click the run history button on the upper right hand corner. This will show a side panel with the historical runs, which you can filter by failed/success, and select the desired date range. Results are paginated to support long run histories of up to 3 months.

At the bottom of the node details page are details about the run resources, run list, and node attributes. Clicking the tabs will switch between these three views. The resources view lets you see which resources are failed, successful, unchanged and unprocessed. Clicking on the tabs with these names will filter the list to show only those resources.

The run list view shows cookbooks, roles and recipes. For a node using policyfiles, you will be able to see the policy ID’s for each cookbook listed. The attribute view shows a list of attributes, which you are able to expand and search through. The search will highlight the matching attributes and searches through values and keys within the attribute json structure. The attributes can also be filtered by default, normal, override and automatic attributes. Learn more about attributes

When looking at a failed run, clicking on “view error log” button at the top of the page will display a pop up showing the error message, and backtrace. The error message can be downloaded from the pop up using the download button.

Managing Node Data

Managing Missing Nodes

You can configure when nodes are marked missing and when they are deleted from General Settings on the Admin tab

Deleting Missing Nodes

Admins and users with permission for this action (defined in their access policies) can delete missing nodes from the Chef Client Runs page. Deleting nodes works only on missing nodes; active nodes cannot be deleted.

To delete one or more missing nodes, tic the checkbox to the left of the node name and then select the red delete button above the table header. Confirm the delete action in the pop-up window.

To delete all missing nodes, tic the checkbox in the heading row of the client runs table, which selects all of the All missing nodes on the current page will then be selected. The user can choose to deselect individual nodes by un-checking the checkboxes next to nodes. Select the delete button and confirm the delete action in the pop-up window.

Deleting Missing Nodes from the Command Line

Nodes can also be deleted with the Chef Automate CLI or through the Chef Automate REST API.

To delete a node from the Chef Client Runs page using the Chef Automate CLI, first locate the node id on the node details page and use this id with the node-delete command:

chef-automate infrastructure node-delete 3f2a2830-0ef3-474a-a835-3a7dd25361fe

To delete nodes using the REST API, use the "https://automate-url/api/v0/ingest/events/chef/nodedelete" to delete a single node, or the "https://automate-url/api/v0/ingest/events/chef/node-multiple-deletes" endpoint to delete multiple nodes. To identify the node or nodes, use either the node_id –which is the UUID of the node as it appears in Automate–or the combination of node name, organization name, and service hostname. The service hostname is the fqdn of your Chef Server or, in the case of chef-solo nodes, localhost.

Request for deleting a node using the node_id

curl -sSX POST "https://automate-url/api/v0/ingest/events/chef/nodedelete" -d
'{
  "node_id": "3f2a2830-0ef3-474a-a835-3a7dd25361fe"
}'
-H "X-Data-Collector-Token: $TOKEN"

Request for deleting multiple nodes using the node_id

curl -sSX POST "https://automate-url/api/v0/ingest/events/chef/node-multiple-deletes" -d
'{
  "node_ids": ["3f2a2830-0ef3-474a-a835-3a7dd25361fe", "9c139ad0-89a5-44bc-942c-d7f248b155ba"]
}'
-H "X-Data-Collector-Token: $TOKEN"

Request for deleting a node using the node name, organization name, and service hostname

curl -sSX POST "https://automate-url/api/v0/ingest/events/chef/nodedelete" -d
'{
  "node_name": "somenode",
  "organization_name": "yourorg",
  "service_hostname": "chef-server-fqdn"
}'
-H "X-Data-Collector-Token: $TOKEN"

Managing Ephemeral Nodes

For ephemeral nodes, which are nodes that are frequently created and destroyed, Automate considers the instances as new nodes by default, even if the node repeatedly uses the same name. To change this behavior–making Automate consider ephemeral nodes as manifestations of the same node–configure the UUID on the client side. In the client.rb file for the node, set chef_guid to the desired UUID. If the node already exists, check that it uses the current UUID, otherwise it will appear as a new node the next time it is recreated. Configuring the UUID on the client side keeps the node associated with the same id, which makes Automate consider it as the same node every time it is recreated.

See the client.rb documentation for more information about configuring your client nodes.

The following are the configuration parameters available:

Parameter Type Explanation Format Default
threshold string The duration after which unreported nodes are marked as missing. 1h30m, 1m, 2h30m, 1d, etc. 1d
every string How often to scan the nodes to check if they are missing. 1h30m, 1m, 2h30m, 1d, etc. 15m
running boolean Is the job running? Set to false to turn off missing node functionality. n/a true

Below is an example curl command:

curl -sSX POST "https://automate-url/api/v0/ingest/job/missing-nodes/config" -d
'{
  "threshold": "1d",
  "every": "15m",
  "running": true
}'
-H "api-token: $TOKEN"

You will need an API token to send API requests. You can either create a new token or use an Automate 1 data collector token if you are migrating from Chef Automate 1.

Configuring Data Cleanup

By default, Automate prevents irreversible destructive operations by keeping deleted node history in elasticsearch, unless users configure this functionality. Our recommendation for destroying deleted node history is to set the threshold to 1 day and to run data cleanup every 15 minutes.

The following are the configuration parameters available:

Parameter Type Explanation Format Default
threshold string The duration after which nodes marked for deletion are removed. 1h30m, 1m, 2h30m, 1d, etc. 1d
every string How often to scan for marked nodes for deletion to be removed. 1h30m, 1m, 2h30m, 1d, etc. 15m
running boolean Is the job running, set to true to turn on data cleanup functionality. n/a false

Below is an example curl command with the recommended data cleanup settings:

curl -sSX POST "https://automate-url/api/v0/ingest/job/delete-nodes/config" -d
'{
  "threshold": "1d",
  "every": "15m",
  "running": true
}'
-H "api-token: $TOKEN"

You will need an API token to send API requests. You can either create a new token or use an Automate 1 data collector token if you are migrating from Chef Automate 1.