Product SiteDocumentation Site

Chapter 20. Tags

20.1. Associating Tags With a Host, User or VM
20.2. Parent Tags
The tags collection provides information about tags in a Red Hat Enterprise Virtualization environment. An API user accesses this information through the rel="tags" link obtained from the entry point URI (see Chapter 4, Entry Point).
The tag specific elements which may be contained in the tag description are as follows:

Element property icons

The icons used in the properties column of this table are described in Table 8.1, “Element property icons”
Element Type Description Properties
host complex A reference to the host which the tag is attached. See Chapter 13, Hosts
user complex A reference to the user which the tag is attached. See Chapter 18, Users
vm complex A reference to the VM which the tag is attached. See Chapter 14, Virtual Machines
Example 20.1. An XML representation of a tag resource
<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/rhevm-api/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
</tag>

When creating a new tag the name property is required. The name and description elements may be updated post-creation.

20.1. Associating Tags With a Host, User or VM

The collection referenced by link rel="tags" from a host, user or vms represents the set of tags associated with the entity.
The tag representations are as described in Chapter 20, Tags, except they also contain a host id, user id or vm id reference to the entity in question.
Each tags collection may be manipulated as described in Chapter 8, Common Features. Associating a tag with an entity is achieved by POSTing a tag reference (identifying the tag either by its id or name) to the collection. Removing an association is achieved by DELETEing the appropriate element in the collection. 
POST /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags HTTP/1.1
Accept: application/xml
Content-Type: application/xml

<tag>
    <name>Finance</name>
</tag>

HTTP/1.1 201 Created
Location: http://{host}/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e
Content-Type: application/xml

<tag id="f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e"
  href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/
  f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e">
    <name>Finance</name>
    <description>Resources for the Finance department</description>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720"/>
</tag>

DELETE /rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720/tags/f436ebfc-67f2-41bd-8ec6-902b6f7dcb5e HTTP/1.1

HTTP/1.1 204 No Content
To query the set of entities associated with a given tag, the collection/search URI template for the appropriate collection should be used to search for entities matching tag=MyTag. 
GET /rhevm-api/vms?search=tag%3DFinance HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<vms>
    <vm id="5114bb3e-a4e6-44b2-b783-b3eea7d84720"
      href="/rhevm-api/vms/5114bb3e-a4e6-44b2-b783-b3eea7d84720">
        ...
    </vm>
    ...
</vms>