Tags¶
Table of Contents
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.
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 Tags.
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
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. |