Introduction

Purpose

This is a functional specification of the AWS style tags that allow users to store metadata of various resources in the CloudStack cloud (see more information of supported resources below).

References

Feature specification

Tag is the first class object in the CloudStack. It can be created for the following resource types:

  • UserVm - virtual machine,

  • Template - virtual machine image,

  • ISO - ISO image,

  • Volume - virtual machine block device,

  • Snapshot - virtual machine volume snapshot,

  • Network - network where address ranges and other information specified,

  • LoadBalancer - load ballancer appliance,

  • PortForwardingRule,

  • FirewallRule,

  • SecurityGroup - elementary firewall for basic zone and for kvm-advanced zone,

  • SecurityGroupRule - certain traffic permit rule in SG,

  • PublicIpAddress,

  • Project - logical entity which organizes VMs and accounts into collaboration,

  • Vpc - virtual private cluster,

  • NetworkACL,

  • StaticRoute,

  • VMSnapshot - virtual machine (state, RAM, volumes) snapshot,

  • User - user, who accesses CloudStack,

  • Account - account which organizes users and manages owns cloud resources (CLOUDSTACK-10170, 4.12).

DB Changes:

All tags will be stored in `cloud`.`resource_tags` table. The table fields:

  • resource_id
  • resource_type
  • key
  • value
  • account_id
  • domain_id
  • customer

Unique key constraint / index: resourceId/resourceType/key

The table has to be partitioned based on resourceType

Api Changes:

New commands:

createTags

  • resourceIds (required)
  • resourceType (required)
  • tags - map of key/value pairs (required)

Tag can be created for the multiple resources of the same type with a single createTags command.

Example:command=createTags&resourceIds=1,10,12&resourceType=userVm&tags0.key=region&tags0.value=canada&tags1.key=city&tags1.value=TorontoAs a result, the tags with keys region and city will be created for the vms with id=1, 10 and 12

deleteTags

  • resourceIds(required)
  • resourceType (required)
  • tags - Key/value pairs (keys are required, values are optional). If key is specified along with the value, the tag will be removed only when the actual key has the same value specified in the api request

Examples:1) command=deleteTags&resourceIds=1,12&resourceType=Snapshot&tags0.key=cityAs a result, all tags with the key "city" will be removed for Snapshots with id=1,122) command=deleteTags&resourceIds=2&resourceType=Snapshot&tags0.key=city&tags0.value=TorontoThe tag with key=city and value=Toronto will be removed for the snapshot id=2

Tags should also be removed when corresponding resource is expunged.

listTags

  • resourceId (optional)
  • resourceType (optional)
  • key (optional)
  • value (optional)
  • customer

Example:1) command=listTags

Returns all tags for your account.

2) command=listTags&resourceType=Snapshot Returns tags for all snapshots belonging to your account3) command=listTags&key=cityReturns tags for all resource types/resources of your account having the tag=city

4) command=listTags&customer=customerName

Return tags for all the resources the caller is authorized to see, and all tags should be mapped to specific customerName.

Changes to existing commands:

Added "tags" optional parameter to the following existing list commands:

  • listVirtualMachines
  • listVolumes
  • listSnapshots
  • listNetworks
  • listTemplates
  • listIsos
  • listFirewallRules
  • listPortForwardingRules
  • listPublicIpAddresses
  • listSecurityGroups
  • listLoadBalancerRules
  • listProjects
  • listVPCs
  • listNetworkACLs
  • listStaticRoutes

Command example:

0 (http://localhost:8096/?command=listVolumes&listAll=true&tags.value=canada&tags1.key=city&tags1.value=Toronto" class="external-link" rel="nofollow"linktype="raw" wikidestination="http://localhost:8096/?command=listVolumes&listAll=true&tags0.key=region&tags0.value=canada&tags1.key=city&tags1.value=Toronto" originalalias="http://localhost:8096/?command=listVolumes&listAll=true&tags0.key=region&tags0.value=canada&tags1.key=city&tags1.value=Toronto" >.key=region&tags0.value=canada&tags1.key=city&tags1.value=Toronto" class="external-link" rel="nofollow">http://localhost:8096/?command=listVolumes&listAll=true&tags0.key=region&tags0.value=canada&tags1.key=city&tags1.value=Toronto

In this case we'll return all the volumes having tag region=canada OR tag city=Toronto (the same way Amazon does)

Implementation details, getting started notes

All supported tags can be found in source file ResourceTag.java (master branch link):

public enum ResourceObjectType {
   UserVm(true, true),
   Template(true, true),
   ISO(true, false),
   Volume(true, true),
   Snapshot(true, false),
   ...

Only items with first argument = "true" support tags, e.g. Zone:

Zone(false, true)

doesn't support resource tags. If a developer wishes to add new tag next actions should be maintained:

  1. change api/src/com/cloud/server/ResourceTag.java (add new enum item);
  2. change server/src/com/cloud/tags/TaggedResourceManagerImpl.java (modify the code if necessary);
  3. modify integration tests for tags: test/integration/component/test_tags.py and add required tests for new resource type.

Limitations:

  • No tags for remote access VPN as this object doesn't have an ID.
  • No labels