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.
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
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. |