12. Tags
User can define a set of free-form tags to group and identify a subset of their servers. Tags can be for example webserver, database, PROD, QA, DEV etc.
A server can have several tags. API can be used to return only servers matching specified tags. Note that all operations changing server's state or attributes must still be done individually for each server UUID, tags can be used only to return a list of servers.
Creating and modifying tags is allowed only by main account. Subaccounts have access only to listing tags and tagged servers they are granted access to.
List existing tags
Returns all existing tags with their properties and servers tagged.
Request
Normal response
{
"tags": {
"tag": [
{
"description": "Development servers",
"name": "DEV",
"servers": {
"server": [
"0077fa3d-32db-4b09-9f5f-30d9e9afb565"
]
}
},
{
"description": "My own servers",
"name": "private",
"servers": {
"server": []
}
},
{
"description": "Production servers",
"name": "PROD",
"servers": {
"server": []
}
}
]
}
}
Create a new tag
Creates a new tag. Existing servers can be tagged in same request.
Request
{
"tag": {
"name": "DEV",
"description": "Development servers",
"servers": {
"server": [
"0077fa3d-32db-4b09-9f5f-30d9e9afb565"
]
}
}
}
Normal response
{
"tag": {
"name": "DEV",
"description": "Development servers",
"servers": {
"server": [
"0077fa3d-32db-4b09-9f5f-30d9e9afb565"
]
}
}
}
Attributes
Attributes | Accepted values | Default value | Required | Description |
---|---|---|---|---|
name | 1-32 characters A-Z, a-z, 0-9, _ | Yes | The new tag | |
description | A string of max 255 characters | No | Description of the tag | |
servers | A server element with a list of server UUIDs |
No | List of valid UUIDs of existing servers to be tagged |
Error responses
HTTP status | Error code | Description |
---|---|---|
400 | TAG_INVALID | The tag name is invalid |
403 | TAG_FORBIDDEN | Username does not have access to this tag |
409 | TAG_EXISTS | Tag already exists |
Modify existing tag
Changes attributes of an existing tag
Request
{
"tag": {
"name": "PROD",
"description": "Production servers",
"servers": {
"server": [
"0077fa3d-32db-4b09-9f5f-30d9e9afb565"
]
}
}
}
Normal response
{
"tag": {
"name": "PROD",
"description": "Production servers",
"servers": {
"server": [
"0077fa3d-32db-4b09-9f5f-30d9e9afb565"
]
}
}
}
Error responses
HTTP status | Error code | Description |
---|---|---|
400 | TAG_INVALID | The tag name is invalid |
403 | TAG_FORBIDDEN | Username does not have access to this tag |
404 | TAG_NOT_FOUND | Tag does not exist |
409 | TAG_EXISTS | Tag already exists |
Attributes are same as with new tag creation
Delete tag
Deleting existing tag untags all servers from specified tag and deletes tag definition.
Request
Normal response
Error responses
HTTP status | Error code | Description |
---|---|---|
400 | TAG_INVALID | The tag name is invalid |
403 | TAG_FORBIDDEN | Username does not have access to this tag |
404 | TAG_NOT_FOUND | Tag does not exist |
Assign tag to a server
Servers can be tagged with one or more tags. The tags used must exist.
Request
tags
parameter lists the tags to add to the server as a comma-separated list. E.g. dev,test
Normal response
{
"server": {
"boot_order": "disk",
"core_number": "2",
"firewall": "on",
"hostname": "debian.example.com",
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.0",
"family": "IPv4"
},
{
"access": "public",
"address": "x.x.x.x",
"family": "IPv4"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family": "IPv6"
}
]
},
"license": 0,
"memory_amount": "4096",
"nic_model": "virtio",
"plan": "2xCPU-4GB",
"plan_ipv4_bytes": "345346754423",
"plan_ipv6_bytes": "676300234",
"state": "started",
"storage_devices": {
"storage_device": [
{
"address": "virtio:0",
"part_of_plan": "yes",
"storage": "0169b4f8-051c-4a86-9484-f5b798249949",
"storage_size": 50,
"storage_title": "Debian from a template",
"type": "disk"
}
]
},
"tags": {
"tag": [
"DEV",
"private",
"RHEL"
]
},
"timezone": "UTC",
"title": "My Debian server",
"uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
"video_model": "cirrus",
"vnc": "off",
"vnc_password": "aabbccdd",
"zone": "fi-hel1"
}
}
Error responses
HTTP status | Error code | Description |
---|---|---|
400 | TAG_INVALID | The tag name is invalid |
403 | TAG_FORBIDDEN | Username does not have access to this tag |
404 | TAG_NOT_FOUND | Tag does not exist |
Remove tag from server
Untags tags from given server. The tag(s) must exist.
Request
tags
parameter lists the tags to remove from the server as a comma-separated list. E.g. dev,test
Normal response
{
"server": {
"boot_order": "disk",
"core_number": "2",
"firewall": "on",
"hostname": "debian.example.com",
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.0",
"family": "IPv4"
},
{
"access": "public",
"address": "x.x.x.x",
"family": "IPv4"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family": "IPv6"
}
]
},
"license": 0,
"memory_amount": "4096",
"nic_model": "virtio",
"plan": "2xCPU-4GB",
"plan_ipv4_bytes": "345346754423",
"plan_ipv6_bytes": "676300234",
"state": "started",
"storage_devices": {
"storage_device": [
{
"address": "virtio:0",
"part_of_plan": "yes",
"storage": "0169b4f8-051c-4a86-9484-f5b798249949",
"storage_size": 50,
"storage_title": "Debian from a template",
"type": "disk"
}
]
},
"tags": {
"tag": [
"DEV",
"RHEL"
]
},
"timezone": "UTC",
"title": "My Debian server",
"uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
"video_model": "cirrus",
"vnc": "off",
"vnc_password": "aabbccdd",
"zone": "fi-hel1"
}
}
Error responses
HTTP status | Error code | Description |
---|---|---|
400 | TAG_INVALID | The tag name is invalid |
403 | TAG_FORBIDDEN | Username does not have access to this tag |
404 | TAG_NOT_FOUND | Tag does not exist |