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 node-api-tags-ref-label.

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.