Node filters

A node filter is a search expression used to identify a set of nodes using SQL-like expressions on any namespace and attribute. You can create node filters that include or exclude nodes based on specific pattern sets.

When the filter is evaluated, Chef Courier creates a node list from the set of registered nodes at the time that the filter is evaluated.

Create a node filter

1. Create a node filter payload in a JSON file:

   {
      "name": "<FILTER_NAME>",
      "constraints": {
        "attributes": [
          {
            "name": "<ATTRIBUTE_NAME>",
            "operator": "<OPERATOR>",
            "value": [
              "<ATTRIBUTE_VALUE>"
            ],
            "namespace": [
              "<NAMESPACE_NAME>"
            ]
          }
        ],
        "skills": [
          {
            "name": "<SKILL_NAME>",
            "version": [
              "<SKILL_VERSION>"
            ]
          }
        ],
        "enrollmentLevel": {
          "operator": "<ENROLLMENT_LEVEL_OPERATOR>",
          "value": [
            "<ENROLLMENT_LEVEL_VALUES>"
          ]
        },
        "healthStatus": {
          "operator": "<HEALTH_STATUS_OPERATOR>",
          "value": [
            "<HEALTH_STATUS_VALUES>"
          ]
        }
      }
   }
   

   Replace the following:

   • <FILTER_NAME>: a name for the filter

   • <ATTRIBUTE_NAME>: an attribute to filter by

   • <OPERATOR>: an filter operator. The supported operators are:

     • MATCHES
     • CONTAINS
     • =
     • !=

   • <ATTRIBUTE_VALUE>: the attribute value filter operator matches against

   • <NAMESPACE_NAME>: the namespace to search in. The following namespaces are supported:

     • agent for node attributes collected from the Node Management Agent
     • gohai for node attributes collected by the Gohai skill
     • aws for AWS-specific attributes collected by the Gohai skill
     • azure for Azure-specific attributes collected by the Gohai skill
     • tags for tags applied to nodes using Node Management

   • <SKILL_NAME>: the name of the skill to filter by

   • <SKILL_VERSION>: the version of the skill to filter by

   • <ENROLLMENT_LEVEL_OPERATOR>: an operator. The support operators are:

     • =
     • !=

   • <ENROLLMENT_LEVEL_VALUES>: the enrollment level to filter by

   • <HEALTH_STATUS_OPERATOR>: an operator. The support operators are:

     • =
     • !=

   • <HEALTH_STATUS_VALUES>: the health status to filter by

2. Create and save a node filter:

   chef-node-management-cli management filter create-filter --body-file <FILTER_FILENAME> --profile <NODE_MANAGER_PROFILE_NAME>
   

   The response is similar to the following:

   {
       "item": {
       "filterId": "ab38aed7-f35a-4e44-90f5-ef9ea11e6464"
       }
   }
   

Get nodes from a filter

To get nodes from an adhoc filter, use the filter run-adhocFilter subcommand:

chef-node-management-cli management filter run-adhocFilter --body-file <FILTER_FILENAME> --profile <NODE_MANAGER_PROFILE_NAME>

To get nodes from a saved filter, use the filter run-savedFilter subcommand:

chef-node-management-cli management filter run-savedFilter --filterId <FILTER_ID> --profile <NODE_MANAGER_PROFILE_NAME>