6.12. Tags

The Tag API provides functionality to automatically categorize nodes into groups based on data present in a node’s catalogs or by manually assigning a tag to a node. When done automatically, tag matching is done using a series of rules. If all rules of a given tag match the latest version of a node’s catalog set, then that tag will be assigned to the node. A node may be assigned many tags, both automatically through rules matching or manually by the user.

Upon discovering a node, the tag will be assigned based on all existing tag definitions in the system. Tags for all nodes will be re-generated whenever a tag definition is added. Tags that are currently assigned to a node are not automatically removed from nodes when the rules backing a tag are deleted.

Example

With a node that has the following catalog fields:

{
  "source": "dmi",
  "data": {
      "Base Board Information": {
          "Manufacturer": "Intel Corporation"
      }
  },
  "memory": {
      "total": "32946864kB"
      "free": "31682528kB"
  }
  /* ... */
}

We could match against these fields with this tag definition:

{
  "name": "Intel 32GB RAM",
  "rules": [
    {
      "path": "dmi.Base Board Information.Manufacturer",
      "contains": "Intel"
    },
    {
      "path": "dmi.memory.total",
      "equals": "32946864kB"
    }
  ]
}

In both cases, the “path” string starts with “dmi” to signify that the rule should apply to the catalog with a “source” value of “dmi”.

This example makes use of the “contains” and “equals” rules. See the table at the bottom of this document for a list of additional validation rules that can be applied.

6.12.1. API commands

When running the on-http process, these are some common API commands you can send.

If you want to view or manipulate tags directly on nodes, please see the API notes at In Band Management Settings.

Create a New tag

POST /api/current/tags
{
  "name": "Intel-32GB-RAM",
  "rules": [
    {
      "path": "dmi.Base Board Information.Manufacturer",
      "contains": "Intel"
    },
    {
      "path": "ohai.dmi.memory.total",
      "equals": "32946864kB"
    }
  ]
}

Get List of tags

GET /api/current/tags
curl <server>/api/current/tags

Get Definition for a Single tag

GET /api/current/tags/:tagname
curl <server>/api/current/tags/<tagname>

Delete a Single tag

DELETE /api/current/tags/:tagname
curl -X DELETE <server>/api/current/tags/<tagname>

List nodes with a tag

GET /api/current/tags/:tagname/nodes
curl <server>/api/current/tags/<tagname>/nodes

Post a workflow to all nodes with a tag

POST /api/current/tags/:tagname/nodes/workflows
curl -H "Content-Type: application/json" -X POST -d @options.json <server>/api/current/tags/<tagname>/nodes/workflows

6.12.2. Tag JSON format

Tag objects are defined via JSON using these fields:

Name Type Flags Description
name String required, unique Unique name identifying this SKU definition.
rules Object[] required Array of validation rules that define the SKU.
rules[].path String required Path into the catalog to validate against.
rules[].equals * optional Exact value to match against.
rules[].in *[] optional Array of possibly valid values.
rules[].notIn *[] optional Array of possibly invalid values.
rules[].contains String optional A string that the value should contain.
rules[].notContains String optional A string that the value should not contain.
rules[].greaterThan Number optional Number that the value should be greater than.
rules[].lessThan Number optional Number that the value should be less than.
rules[].min Number optional Number that the value should be greater than or equal to.
rules[].max Number optional Number that the value should be less than or equal to.
rules[].regex String optional A regular expression that the value should match.
rules[].notRegex String optional A regular expression that the value should not match.