Client Runs

Overview

The client runs page shows all of the nodes connected to Chef Automate, either directly or via a Chef Server proxy. Nodes appear in this view after chef-client run has been executed.

Chef Client Run Status Overview

The Chef Client Run Status chart displays a summary of node statuses: failed, successful, or missing, as well as the total node count. The chart changes as you select filters.

Client Runs Overview

Node List Table

The node list table shows all of the nodes connected to Automate. 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. In this case, a no data icon appears and you will be unable to view any node details. The node remains listed as a missing node until it is deleted from Automate. Automate automatically removes any modes deleted from the Chef Server.

Node Details

The node details table displays the most recent converge results. You’ll find more information about Resources, Run List, and Attributes in the tabs below the node detail chart. Select the tabs to switch between these three views.

Resources displays the status of the most recent resources are failed, successful, unchanged and unprocessed. Selecting the tabs with these names will filter the list to show only those resources. Run List shows cookbooks, roles and recipes. For a node using policyfiles, you will be able to see the policy ID’s for each cookbook listed. Attributes shows an expandable list of node properties. Use the search bar to discover the node attributes by attribute name, key name, or value. The search results show by highlighting matching attributes. Use the default, normal, override, and automatic buttons beneath the search bar to filter attributes by to these categories. Learn more about attributes

When looking at a failed Chef client run, selecting “view error log” button at the top of the page opens a window showing the error message and backtrace. Use the downloaded button to save the error message.

Selecting a node from the node list table opens the node details page with the most recent information about that node. To look at past run data, select the Run History button on the upper right, which opens a side panel containing historical run data. You can filter this data using the run status icons and by date range. Node history data supports up to three months of client-run information. Scroll through the node history using the pagination buttons at the bottom of the side panel. Use the “X” button at the top of the panel to close the side panel.

Filtering

Filter nodes from the search bar based on existing node information. You can apply multiple filters to a search. The node list table changes to display only nodes that satisfy all of the applied filters. To apply a filter, first select the filter from the dropdown list and begin typing to display autocomplete options. To save a search, select the share button to the right of the search bar, and copy the private URL.

Node Filters

Attribute
Search for an attribute key, this will not search across attribute values.
Chef Organization
A Chef Server organization name.
Chef Server
A Chef Server URL.
Cookbook
A cookbook name.
Environment
Nodes can have one environment.
Node Name
Name of the node.
Platform
OS Platform of a node.
Policy Group
Policy group name, only nodes using policyfiles will be shown.
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.
Recipe
A recipe within a cookbook.
Resource Name
A resource within a cookbook.
Role
Search by nodes assigned to a role. Nodes can have zero or many roles.

See more about policyfiles.

Managing Node Data

Managing Missing Nodes

Configure the timing for marking nodes as missing and then deleting them from Node Lifecycle on the Settings tab.

Deleting Missing Nodes

Admins and users with the relevant permissions defined in access policies, can delete missing nodes from the Chef Client Runs page. Only missing nodes can be deleted; active nodes cannot be deleted.

To delete one or more missing nodes, tick 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, tick the checkbox at the top 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 unchecking 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 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" endpoint to delete a single node, or the "https://automate-url/api/v0/ingest/events/chef/node-multiple-deletes" endpoint to delete multiple nodes. Identify your node or nodes, with 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

Automate considers the instances of ephemeral nodes, which are nodes that are frequently created and destroyed, as new nodes by default, even if the node repeatedly uses the same name. Set Automate to consider ephemeral nodes as manifestations of the same node by configuring the UUID on the client side. 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. In the node’s client.rb, set chef_guid to the desired UUID. If the node already exists, check that it uses the correct UUID, otherwise it will appear as a new node the next 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/retention/nodes/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. Chef recommends setting the threshold for destroying deleted node history to 1 day and running data cleanup every 15 minutes.

Available data cleanup configuration parameters:

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/retention/nodes/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 a Chef Automate 1 data collector token if you are migrating from Chef Automate 1.