en-US/tagging-resources.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file:///C:/Program%20Files%20(x86)/Publican/DocBook_DTD/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>

<!-- Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    
    http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
-->

<section id="tagging-resources">
	<title>Using Tags to Organize Resources in the Cloud</title>
        <para>A tag is a key-value pair that stores metadata about a resource in the cloud. Tags are
            useful for categorizing resources. For example, you can tag a user VM with a
            value that indicates the user's city of residence. In this case, the key would
            be "city" and the value might be "Toronto" or "Tokyo." You can then request
            &PRODUCT; to find all resources that have a given tag; for example, VMs for
            users in a given city.</para>
        <para>You can tag a user virtual machine, volume, snapshot, guest network, template,
            ISO, firewall rule, port forwarding rule, public IP address, security group,
            load balancer rule, project, VPC, network ACL, or static route. You can not tag
            a remote access VPN.</para>
        <para>You can work with tags through the UI or through the API commands createTags,
            deleteTags, and listTags. You can define multiple tags for each resource. There
            is no limit on the number of tags you can define. Each tag can be up to 255
            characters long. Users can define tags on the resources they own, and
            administrators can define tags on any resources in the cloud.</para>
        <para>An optional input parameter, "tags," exists on many of the list* API commands. 
            The following example shows how to use this new parameter to find all the volumes
            having tag region=canada OR tag city=Toronto:</para>
        <programlisting>command=listVolumes
				&amp;listAll=true
				&amp;tags[0].key=region
				&amp;tags[0].value=canada
				&amp;tags[1].key=city
				&amp;tags[1].value=Toronto</programlisting>
        <para>The following API commands have the "tags" input parameter:</para>
        <itemizedlist>
            <listitem><para>listVirtualMachines</para></listitem>
            <listitem><para>listVolumes</para></listitem>
            <listitem><para>listSnapshots</para></listitem>
            <listitem><para>listNetworks</para></listitem>
            <listitem><para>listTemplates</para></listitem>
            <listitem><para>listIsos</para></listitem>
            <listitem><para>listFirewallRules</para></listitem>
            <listitem><para>listPortForwardingRules</para></listitem>
            <listitem><para>listPublicIpAddresses</para></listitem>
            <listitem><para>listSecurityGroups</para></listitem>
            <listitem><para>listLoadBalancerRules</para></listitem>
            <listitem><para>listProjects</para></listitem>
            <listitem><para>listVPCs</para></listitem>
            <listitem><para>listNetworkACLs</para></listitem>
            <listitem><para>listStaticRoutes</para></listitem>
        </itemizedlist>
</section>