Overview

ZStack Cloud provides two types of tags to help users and plugins organize resources, introduce extra resource properties, and instruct ZStack Cloud to perform specific business logic.

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

Each user tag and each system tag can only have 2048 characters at most.
  • A user tag does not have any enforced name convention. We recommend that you use readable, meaningful strings.
  • A system tag, as defined by ZStack Cloud service and plugins, follows the format that uses :: as a delimiters.

Resource Type

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

The following table lists the resource types supported in this version.
Resource Type
AccessControlRuleVO
AccessKeyVO
AccountResourceRefVO
AccountVO
AddingNewInstanceRuleVO
AffinityGroupUsageVO
AffinityGroupVO
AlarmActionVO
AlarmLabelVO
AlarmVO
AlertVO
AliyunDiskVO
AliyunEbsBackupStorageVO
AliyunEbsPrimaryStorageVO
AliyunNasAccessGroupVO
AliyunNasAccessRuleVO
AliyunNasFileSystemVO
AliyunNasMountTargetVO
AliyunNasMountVolumeRefVO
AliyunNasPrimaryStorageFileSystemRefVO
AliyunNasPrimaryStorageMountPointVO
AliyunPanguPartitionVO
AliyunProxyVSwitchVO
AliyunProxyVpcVO
AliyunRouterInterfaceVO
AliyunSmsSNSTextTemplateVO
AliyunSnapshotVO
ApplianceVmFirewallRuleVO
ApplianceVmVO
ArchiveTicketStatusHistoryVO
ArchiveTicketVO
AsyncRestVO
AutoScalingGroupActivityVO
AutoScalingGroupInstanceVO
AutoScalingGroupVO
AutoScalingRuleAlarmTriggerVO
AutoScalingRuleTriggerVO
AutoScalingRuleVO
AutoScalingTemplateGroupRefVO
AutoScalingTemplateVO
AutoScalingVmTemplateVO
AvailableInstanceTypesVO
BackupStorageEO
BackupStorageVO
BackupStorageZoneRefVO
BaremetalBondingVO
BaremetalChassisVO
BaremetalHardwareInfoVO
BaremetalImageCacheVO
BaremetalInstanceSequenceNumberVO
BaremetalInstanceVO
BaremetalNicVO
BaremetalPxeServerClusterRefVO
BaremetalPxeServerVO
BaremetalVlanNicVO
BareMetal2ChassisVO
BareMetal2ChassisNicVO
BareMetal2ChassisDiskVO
BareMetal2ChassisOfferingVO
BareMetal2InstanceVO
BareMetal2GatewayVO
BareMetal2ProvisionNetworkVO
BillingResourceLabelVO
BillingVO
BuildApplicationVO
CaptchaVO
CephBackupStorageMonVO
CephBackupStorageVO
CephCapacityVO
CephPrimaryStorageMonVO
CephPrimaryStoragePoolVO
CephPrimaryStorageVO
CertificateVO
CloudFormationStackEventVO
CloudFormationStackResourceRefVO
ClusterEO
ClusterVO
ConnectionAccessPointVO
ConnectionRelationShipVO
ConsoleProxyAgentVO
ConsoleProxyVO
CustomPreconfigurationVO
DataCenterVO
DataVolumeBillingVO
DataVolumeUsageExtensionVO
DataVolumeUsageHistoryVO
DataVolumeUsageVO
DatabaseBackupStorageRefVO
DatabaseBackupVO
DeleteVO
DiskOfferingEO
DiskOfferingVO
ESXHostVO
EcsImageUsageVO
EcsImageVO
EcsInstanceVO
EcsSecurityGroupRuleVO
EcsSecurityGroupVO
EcsVSwitchVO
EcsVpcVO
EipVO
ElaborationVO
EmailMediaVO
EmailTriggerActionVO
EventSubscriptionActionVO
EventSubscriptionLabelVO
EventSubscriptionVO
FiberChannelLunVO
FiberChannelStorageVO
FlowCollectorVO
FlowMeterVO
FlowRouterVO
GarbageCollectorVO
GlobalConfigTemplateVO
GlobalConfigVO
GuestToolsVO
HardwareL2VxlanNetworkPoolVO
HistoricalPasswordVO
HostCapacityVO
HostEO
HostTagVO
HostVO
HybridAccountVO
HybridConnectionRefVO
HybridEipAddressVO
IAM2GroupVirtualIDRefVO
IAM2OrganizationAttributeVO
IAM2OrganizationProjectRefVO
IAM2OrganizationVO
IAM2ProjectAccountRefVO
IAM2ProjectAttributeVO
IAM2ProjectTemplateVO
IAM2ProjectVO
IAM2ProjectVirtualIDRefVO
IAM2TicketFlowCollectionVO
IAM2TicketFlowVO
IAM2VirtualIDAttributeVO
IAM2VirtualIDGroupAttributeVO
IAM2VirtualIDGroupRefVO
IAM2VirtualIDGroupRoleRefVO
IAM2VirtualIDGroupVO
IAM2VirtualIDOrganizationRefVO
IAM2VirtualIDRoleRefVO
IAM2VirtualIDVO
IPsecConnectionVO
IPsecL3NetworkRefVO
IPsecPeerCidrVO
IdentityZoneVO
ImageBackupStorageRefVO
ImageCacheShadowVO
ImageCacheVO
ImageCacheVolumeRefVO
ImageEO
ImageOpsJournalVO
ImageReplicationGroupBackupStorageRefVO
ImageReplicationGroupVO
ImageReplicationHistoryVO
ImageStoreBackupStorageVO
ImageVO
InsertVO
InstallPathRecycleVO
InstanceOfferingEO
InstanceOfferingVO
IpRangeEO
IpRangeVO
IscsiFileSystemBackendPrimaryStorageVO
IscsiIsoVO
IscsiLunVO
IscsiServerClusterRefVO
IscsiServerVO
IscsiTargetVO
JobQueueEntryVO
JobQueueVO
JsonLabelVO
KVMHostVO
KeyValueBinaryVO
KeyValueVO
L2NetworkClusterRefVO
L2NetworkEO
L2NetworkVO
L2VlanNetworkVO
L3NetworkDnsVO
L3NetworkEO
L3NetworkHostRouteVO
L3NetworkVO
LdapAccountRefVO
LdapResourceRefVO
LdapServerVO
LoadBalancerListenerCertificateRefVO
LoadBalancerListenerVO
LoadBalancerListenerVmNicRefVO
LoadBalancerVO
LocalStorageHostRefVO
LocalStorageResourceRefVO
LogVO
LoginAttemptsVO
LongJobVO
ManagementNodeContextVO
ManagementNodeVO
MdevDeviceSpecVO
MdevDeviceVO
MediaVO
MiniStorageHostRefVO
MiniStorageResourceReplicationVO
MiniStorageVO
MirrorNetworkUsedIpVO
MonitorTriggerActionRefVO
MonitorTriggerActionVO
MonitorTriggerVO
MulticastRouterRendezvousPointVO
MulticastRouterVO
MulticastRouterVpcVRouterRefVO
NasFileSystemVO
NasMountTargetVO
NetworkRouterAreaRefVO
NetworkRouterFlowMeterRefVO
NetworkServiceL3NetworkRefVO
NetworkServiceProviderL2NetworkRefVO
NetworkServiceProviderVO
NetworkServiceTypeVO
NotificationSubscriptionVO
OssBucketDomainVO
OssBucketVO
OssUploadPartsVO
PciDeviceBillingVO
PciDeviceMdevSpecRefVO
PciDeviceOfferingInstanceOfferingRefVO
PciDeviceOfferingVO
PciDevicePciDeviceOfferingRefVO
PciDeviceSpecVO
PciDeviceUsageHistoryVO
PciDeviceUsageVO
PciDeviceVO
PhysicalDriveSmartSelfTestHistoryVO
PolicyRouteRuleSetL3RefVO
PolicyRouteRuleSetVO
PolicyRouteRuleSetVRouterRefVO
PolicyRouteRuleVO
PolicyRouteTableRouteEntryVO
PolicyRouteTableVO
PolicyRouteTableVRouterRefVO
PolicyVO
PortForwardingRuleVO
PortMirrorSessionMirrorNetworkRefVO
PortMirrorSessionSequenceNumberVO
PortMirrorSessionVO
PortMirrorVO
PreconfigurationTemplateVO
PricePciDeviceOfferingRefVO
PriceVO
PrimaryStorageCapacityVO
PrimaryStorageClusterRefVO
PrimaryStorageEO
PrimaryStorageHostRefVO
PrimaryStorageVO
PubIpVipBandwidthInBillingVO
PubIpVipBandwidthOutBillingVO
PubIpVipBandwidthUsageHistoryVO
PubIpVipBandwidthUsageVO
PubIpVmNicBandwidthInBillingVO
PubIpVmNicBandwidthOutBillingVO
PubIpVmNicBandwidthUsageVO
QuartzJdbcJobVO
QuotaVO
RaidControllerVO
RaidPhysicalDriveVO
RemovalInstanceRuleVO
ResourceConfigVO
ResourceStackVO
ResourceUsageVO
ResourceVO
RoleAccountRefVO
RolePolicyRefVO
RolePolicyStatementVO
RoleUserGroupRefVO
RoleUserRefVO
RoleVO
RootVolumeBillingVO
RootVolumeUsageExtensionVO
RootVolumeUsageVO
RouterAreaVO
SNSApplicationEndpointVO
SNSApplicationPlatformVO
SNSDingTalkAtPersonVO
SNSDingTalkEndpointVO
SNSEmailAddressVO
SNSEmailEndpointVO
SNSEmailPlatformVO
SNSHttpEndpointVO
SNSSmsEndpointVO
SNSSmsReceiverVO
SNSSubscriberVO
SNSTextTemplateVO
SNSTopicVO
SchedulerJobGroupJobRefVO
SchedulerJobGroupSchedulerTriggerRefVO
SchedulerJobGroupVO
SchedulerJobHistoryVO
SchedulerJobSchedulerTriggerRefVO
SchedulerJobVO
SchedulerTriggerVO
SchedulerVO
ScsiLunHostRefVO
ScsiLunVO
ScsiLunVmInstanceRefVO
SdnControllerVO
SecurityGroupFailureHostVO
SecurityGroupL3NetworkRefVO
SecurityGroupRuleVO
SecurityGroupSequenceNumberVO
SecurityGroupVO
SessionVO
SftpBackupStorageVO
ShareableVolumeVmInstanceRefVO
SharedBlockGroupPrimaryStorageHostRefVO
SharedBlockGroupVO
SharedBlockVO
SharedResourceVO
SimulatorHostVO
SnapShotUsageVO
StackTemplateVO
SystemRoleVO
SystemTagVO
TagPatternVO
TaskProgressVO
TemplateConfigVO
TemplateCustomParamVO
TicketFlowCollectionVO
TicketFlowVO
TicketStatusHistoryVO
TicketTypeTicketFlowCollectionRefVO
TicketTypeVO
TicketVO
TwoFactorAuthenticationSecretVO
UpdateVO
UsbDeviceVO
UsedIpVO
UserGroupPolicyRefVO
UserGroupUserRefVO
UserGroupVO
UserPolicyRefVO
UserTagVO
UserVO
V2VConversionCacheVO
V2VConversionHostVO
VCenterBackupStorageVO
VCenterClusterVO
VCenterDatacenterVO
VCenterPrimaryStorageVO
VCenterResourcePoolUsageVO
VCenterResourcePoolVO
VCenterVO
VRouterRouteEntryVO
VRouterRouteTableVO
VipNetworkServicesRefVO
VipPeerL3NetworkRefVO
VipQosVO
VipVO
VirtualBorderRouterVO
VirtualRouterBootstrapIsoVO
VirtualRouterEipRefVO
VirtualRouterLoadBalancerRefVO
VirtualRouterOfferingVO
VirtualRouterPortForwardingRuleRefVO
VirtualRouterVRouterRouteTableRefVO
VirtualRouterVipVO
VirtualRouterVmVO
VmCPUBillingVO
VmCdRomVO
VmInstanceEO
VmInstanceMdevDeviceSpecRefVO
VmInstanceMdevSpecDeviceRefVO
VmInstancePciDeviceSpecRefVO
VmInstancePciSpecDeviceRefVO
VmInstanceSequenceNumberVO
VmInstanceVO
VmMemoryBillingVO
VmNicSecurityGroupRefVO
VmNicVO
VmPriorityConfigVO
VmUsageVO
VniRangeVO
VolumeBackupHistoryVO
VolumeBackupStorageRefVO
VolumeBackupVO
VolumeEO
VolumeSnapshotBackupStorageRefVO
VolumeSnapshotEO
VolumeSnapshotGroupRefVO
VolumeSnapshotGroupVO
VolumeSnapshotTreeEO
VolumeSnapshotTreeVO
VolumeSnapshotVO
VolumeVO
VpcFirewallRuleSetL3RefVO
VpcFirewallRuleSetVO
VpcFirewallRuleVO
VpcFirewallVO
VpcFirewallVRouterRefVO
VpcHaGroupApplianceVmRefVO
VpcHaGroupMonitorIpVO
VpcHaGroupNetworkServiceRefVO
VpcHaGroupVO
VpcHaGroupVipRefVO
VpcRouterDnsVO
VpcRouterVmVO
VpcUserVpnGatewayVO
VpcVirtualRouteEntryVO
VpcVirtualRouterVO
VpcVpnConnectionVO
VpcVpnGatewayVO
VpcVpnIkeConfigVO
VpcVpnIpSecConfigVO
VtepVO
VxlanNetworkPoolVO
VxlanNetworkVO
WebhookVO
WorkFlowChainVO
WorkFlowVO
XDragonHostVO
ZoneEO
ZoneVO

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


Inventory

System Tag Inventory

Name Description Optional Valid Value Starting Version
uuid The UUID. For more information, see Resource Property. 0.6
createDate The creation date. For more information, see Resource Property. 0.6
lastOpDate The last operation date. For more information, see Resource Property. 0.6
resourceUuid The resource UUID. 0.6
resourceType The resource type. 0.6
tag Th tag string. 0.6
type The reserved field. 0.6
groupBy Groups rows into subgroups based on values of columns or expressions. This field is equivalent to the Group By clause in MySQL, such as groupBy=type. Yes 1.9
systemTags The system tags. For more information, see CreateSystemTag. Yes 0.6
userTags The user tags. For more information, see CreateUserTag. Yes 0.6

Tag Inventory

Name Description Optional Valid Value Starting Version
uuid The UUID. For more information, see Resource Property. 3.2.0
createDate The creation date. For more information, see Resource Property. 3.2.0
lastOpDate The last operation date. For more information, see Resource Property. 3.2.0
value 3.2.0
description The detailed description of the resource. 3.2.0
color 3.2.0
type The reserved field. 3.2.0
groupBy Groups rows into subgroups based on values of columns or expressions. This field is equivalent to the Group By clause in MySQL, such as groupBy=type. Yes 3.2.0
systemTags The system tags. For more information, see CreateSystemTag. Yes 3.2.0
userTags The user tags. For more information, see CreateUserTag. Yes 3.2.0
Sample
{
  "inventories": [
    {
      "uuid": "f7ac675964d0386b89d8df713f68aee0",
      "name": "SSD",
      "value": "SSD",
      "description": "SSD volume",
      "color": "#FFFFFF",
      "type": "simple",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}

User Tag Inventory

Name Description Optional Valid Value Starting Version
uuid The UUID. For more information, see Resource Structure. 0.6
createDate The creation date. For more information, see Resource Structure. 0.6
lastOpDate The last operation date. For more information, see Resource Structure. 0.6
resourceUuid The resource UUID. If specified, the system will not allocate randomly a UUID to the resource. 0.6
resourceType The resource type, which must be specified when you create a tag. 0.6
tag The tag string. 0.6
type The reserved field for internal use. 0.6
groupBy Groups rows into subgroups based on values of columns or expressions. This field is equivalent to the Group By clause in MySQL, such as groupBy=type. Yes 0.6
systemTags The system tags. For more information, see CreateSystemTag. Yes 0.6
userTags The user tags. For more information, see CreateUserTag. Yes 0.6
Sample
{
  "inventories": [
    {
      "uuid": "ae4f2dd05a513e1e8d350d448c2071a9",
      "resourceType": "DiskOfferingVO",
      "tag": "for-large-DB",
      "type": "User",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}











Download

Already filled the basic info? Click here.

Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

An email with a verification code will be sent to you. Make sure the address you provided is valid and correct.

Download

Not filled the basic info yet? Click here.

Invalid email address or mobile number.

Email Us

contact@zstack.io
ZStack certification training consulting
Enter at least 2 characters.
Invalid mobile number.
Enter at least 4 characters.
Invalid email address.
Wrong code. Try again. Send Code Resend Code (60s)

Email Us

contact@zstack.io

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder. After receiving the email, click the URL to download the documentation.

The download link is sent to your email address.

If you don't see it, check your spam folder, subscription folder, or AD folder.
Or click on the URL below. (For Internet Explorer, right-click the URL and save it.)

Thank you for using ZStack products and services.

Submit successfully.

We'll connect soon.

Thank you for choosing ZStack products and services.

Back to Top