Overview

User Tags

1. You can create user tags on all the resources that you have, which is especially useful when you aggregate a set of similar resources.
   For example, you can create a web tag on VM instances that act as web servers.

   1. CreateUserTag resourceType=VmInstanceVO \
      resourceUuid=613af3fe005914c1643a15c36fd578c6 tag=web

      CreateUserTag resourceType=VmInstanceVO \
      resourceUuid=5eb55c39db015c1782c7d814900a9609 tag=web

      CreateUserTag resourceType=VmInstanceVO \
      resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 tag=web

   2. Then, you can retrieve these VM instances by using Query API with tags <query with tags>.

      QueryVmInstance __userTag__=web

   When you create a VM instance, you can also set multiple user tags and separate these tags by using a comma (,).

   1. CreateVmInstance instanceOfferingUuid=1cf417bfd0e94175aea92131f1000011  \
      imageUuid=ee14c7c8cc46309d821c51bbae3adb70 l3NetworkUuids=ac5c7e736f1b499bbd0c12763b30051d  \
      name=tesd2 userTags=capability::liveSnapshot,os::centos::7.4

   2. For example, you can set the capacity (40G), OS version (CentOS7.4), password (123456), and usage scenario (Apache) on these tags. These settings have no special relation to ::.

      CreateVmInstance instanceOfferingUuid=1cf417bfd0e94175aea92131f1000011  \
      imageUuid=ee14c7c8cc46309d821c51bbae3adb70 l3NetworkUuids=ac5c7e736f1b499bbd0c12763b30051d name=tesd2   \
      userTags=capability:40G,OS:CentOS7.4,password:123456,usage:Apache

2. You can also integrate user tags with system tags to change the business logic of the cloud.

   For example, you might want all VM instances that work as web servers to create their root volumes on a special primary storage that provides better IO performance by SSD.

   To do so, you can follow the steps below:

   1. Create a user tag forWebTierVM on a primary storage.

      CreateUserTag tag=forWebTierVM resourceType=PrimaryStorageVO \
      resourceUuid=6572ce44c3f6422d8063b0fb262cbc62

   2. Create a system tag on an instance offering.

      CreateSystemTag tag=primaryStorage::allocator::userTag::forWebTierVM \
      resourceType=InstanceOfferingVO resourceUuid=8f69ef6c2c444cdf8c019fa0969d56a5

   3. Then, when you create a VM instance with the instance offering UUID: 8f69ef6c2c444cdf8c019fa0969d56a5, ZStack Cloud will make sure that the root volume of the VM instance will be created on only the primary storage with the user tag forWebTierVM and UUID 6572ce44c3f6422d8063b0fb262cbc62.

System Tags

System tags have wider usage than user tags. You can use system tags to instruct ZStack Cloud to do some specific business logic, like the examples in the section above.

1. Inherent System Tags

   Plugins, which extend the functionality of ZStack Cloud, can use system tags to introduce additional resource properties, or to record metadata that tightly bind to resources.

   For example, you might want to perform online migrations or online snapshots on KVM instances.

   ZStack Cloud needs to know the libvirt version and QEMU version of the KVM instances, which are all meta data. ZStack Cloud records these data as system tags of VM instances.

   1. For example, you can view the system tags of a KVM VM instance by running the following command:

      QuerySystemTag fields=tag resourceUuid=d07066c4de02404a948772e131139eb4

   2. d07066c4de02404a948772e131139eb4 is the UUID for the KVM instance. The query result is as follows:

      {
        "inventories": [
            {
                "tag": "capability:liveSnapshot"
            },
            {
                "tag": "qemu-img::version::2.0.0"
            },
            {
                "tag": "os::version::14.04"
            },
            {
                "tag": "libvirt::version::1.2.2"
            },
            {
                "tag": "os::release::trusty"
            },
            {
                "tag": "os::distribution::Ubuntu"
            }
        ],
        "success": true
      }

   This kind of system tags are called inherent system tags, which can be only created by ZStack Cloud services and plugins, and cannot be deleted by using the DeleteTag API.

2. Non-inherent System Tags

   To add new features, plugins usually need to add a new properties to a resource. Although a plugin cannot add a new column by changing the database schema of a resource, the plugin can create new properties as system tags of a resource.

   For example, when you create a VM instance, you can bind a hostname that can be accessed by the Internet to an L3 network of the VM instance.

   1. CreateVmInstance name=testTag systemTags=hostname::web-server-1 \
      l3NetworkUuids=6572ce44c3f6422d8063b0fb262cbc62 \
      instanceOfferingUuid=04b5419ca3134885be90a48e372d3895 \
      imageUuid=f1205825ec405cd3f2d259730d47d1d8

   2. This hostname is implemented by a system tag.
   3. If you view the VM Instance Inventory in the VM Instance topic, you will find no property called hostname.
   4. However, you can find the hostname from the system tags of the VM instance.

      QuerySystemTag fields=tag uuid resourceUuid=76e119bf9e16461aaf3d1b47c645c7b7

      {
        "inventories": [
            {
                "tag": "hostname::web-server-1",
                "uuid": "596070a6276746edbf0f54ef721f654e"
            }
        ],
        "success": true
      }

   This kind of system tags are non-inherent. You can them by using the DeleteTag API.

   For example, if you want to change the hostname of a VM instance mentioned above to web-server-nginx, you can:

   1. DeleteTag uuid=596070a6276746edbf0f54ef721f654e

   2. CreateSystemTag resourceType=VmInstanceVO tag=hostname::web-server-nginx \
      resourceUuid=76e119bf9e16461aaf3d1b47c645c7b7

   3. After the VM instance is stopped and restarted, the guest operating system will receive the new hostname as web-server-nginx.

Name Convention

Resource Type

When you create a tag, you must specify the resource type that the tag is associated with.

In the corresponding Tags topic of each resource, we will explain what resource types to use when you create tags.