Use tags to organize your Azure resources

You apply tags to your Azure resources to logically organize them by categories. Each tag consists of a key and a value. For example, you can apply the key "Environment" and the value "Production" to all the resources in production. Without this tag, you may have difficulty identifying whether a resource is intended for development, test, or production. However, "Environment" and "Production" are just examples. You define the keys and values that make the most sense for organizing your subscription.

After applying tags, you can retrieve all the resources in your subscription with that tag key and value. Tags enable you to retrieve related resources that reside in different resource groups. This approach is helpful when you need to organize resources for billing or management.

The following limitations apply to tags:

  • Each resource or resource group can have a maximum of 15 tag key/value pairs. This limitation only applies to tags directly applied to the resource group or resource. A resource group can contain many resources that each have 15 tag key/value pairs.
  • The tag name is limited to 512 characters.
  • The tag value is limited to 256 characters.
  • Tags applied to the resource group are not inherited by the resources in that resource group.

If you have more than 15 values that you need to associate with a resource, use a JSON string for the tag value. The JSON string can contain many values that are applied to a single tag key. An example of assigning a JSON string to the tag key is shown in this article.

Note

You can only apply tags to resources that support Resource Manager operations. If you created a Virtual Machine, Virtual Network, or Storage through the classic deployment model (such as through the classic portal), you cannot apply a tag to that resource. To support tagging, redeploy these resources through Resource Manager. All other resources support tagging.

Ensure tag consistency with policies

Resource policies enable you to create standard rules for your organization. You can create policies that ensure resources are tagged with the appropriate values. For more information, see Apply resource policies for tags.

Templates

To tag a resource during deployment, add the tags element to the resource you are deploying. Provide the tag name and value.

Apply literal value to tag name

The following example shows a storage account with two tags (Dept and Environment) that are set to literal values:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
    {
      "apiVersion": "2016-01-01",
      "type": "Microsoft.Storage/storageAccounts",
      "name": "[concat('storage', uniqueString(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "tags": {
        "Dept": "Finance",
        "Environment": "Production"
      },
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": { }
    }
    ]
}

Apply object to tag element

You can define an object parameter that stores several tags, and apply that object to the tag element. Each property in the object becomes a separate tag for the resource. The following example has a parameter named tagValues that is applied to the tag element.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "tagValues": {
      "type": "object",
      "defaultValue": {
        "Dept": "Finance",
        "Environment": "Production"
      }
    }
  },
  "resources": [
    {
      "apiVersion": "2016-01-01",
      "type": "Microsoft.Storage/storageAccounts",
      "name": "[concat('storage', uniqueString(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "tags": "[parameters('tagValues')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

Apply JSON string to tag name

To store many values in a single tag, apply a JSON string that represents the values. The entire JSON string is stored as one tag that cannot exceed 256 characters. The following example has a single tag named CostCenter that contains several values from a JSON string:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
    {
      "apiVersion": "2016-01-01",
      "type": "Microsoft.Storage/storageAccounts",
      "name": "[concat('storage', uniqueString(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "tags": {
        "CostCenter": "{\"Dept\":\"Finance\",\"Environment\":\"Production\"}"
      },
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": { }
    }
    ]
}

Portal

  1. To view the tags for a resource or resource group, select the Tags icon.

    Select tags on resource and resource group blades

  2. You see the existing tags for the resource. If you have not previously applied tags, the list is empty.

    Show existing tags on resource and resource group blades

  3. To add a tag, type a key and value, or select an existing one from the dropdown menu. Select Save.

    Add new tag

  4. To view all the resources with a tag value, select > (More services), and enter the word Tags into the filter text box. Select Tags from the available options.

    Find tags via the Browse hub

  5. You see a summary of the tags in your subscriptions.

    Show all tags

  6. Select any of the tags to display the resources and resource groups with that tag.

    Show tagged resources

  7. Select Pin blade to dashboard for quick access.

    Pin tags to the Dashboard

  8. You can select the pinned tag from the dashboard to see the resources with that tag.

    Pin tags to the Dashboard

PowerShell

Version 3.0 of the AzureRm.Resources module included significant changes in how you work with tags. Before proceeding, check your version:

Get-Module -ListAvailable -Name AzureRm.Resources | Select Version

If your results show version 3.0 or later, the examples in this topic work with your environment. If you do not have version 3.0 or later, update your version by using PowerShell Gallery or Web Platform Installer before proceeding with this topic.

Version
-------
3.5.0

Every time you apply tags to a resource or resource group, you overwrite the existing tags on that resource or resource group. Therefore, you must use a different approach based on whether the resource or resource group has existing tags that you want to preserve. To add tags to a:

  • resource group without existing tags.

    Set-AzureRmResourceGroup -Name TagTestGroup -Tag @{ Dept="IT"; Environment="Test" }
    
  • resource group with existing tags.

    $tags = (Get-AzureRmResourceGroup -Name TagTestGroup).Tags
    $tags += @{Status="Approved"}
    Set-AzureRmResourceGroup -Tag $tags -Name TagTestGroup
    
  • resource without existing tags.

    Set-AzureRmResource -Tag @{ Dept="IT"; Environment="Test" } -ResourceName storageexample -ResourceGroupName TagTestGroup -ResourceType Microsoft.Storage/storageAccounts
    
  • resource with existing tags.

    $tags = (Get-AzureRmResource -ResourceName storageexample -ResourceGroupName TagTestGroup).Tags
    $tags += @{Status="Approved"}
    Set-AzureRmResource -Tag $tags -ResourceName storageexample -ResourceGroupName TagTestGroup -ResourceType Microsoft.Storage/storageAccounts
    

To apply all tags from a resource group to its resources, and not retain existing tags on the resources, use the following script:

$groups = Get-AzureRmResourceGroup
foreach ($g in $groups) 
{
    Find-AzureRmResource -ResourceGroupNameEquals $g.ResourceGroupName | ForEach-Object {Set-AzureRmResource -ResourceId $_.ResourceId -Tag $g.Tags -Force } 
}

To apply all tags from a resource group to its resources, and retain existing tags on resources that are not duplicates, use the following script:

$groups = Get-AzureRmResourceGroup
foreach ($g in $groups) 
{
    if ($g.Tags -ne $null) {
        $resources = Find-AzureRmResource -ResourceGroupNameEquals $g.ResourceGroupName 
        foreach ($r in $resources)
        {
            $resourcetags = (Get-AzureRmResource -ResourceId $r.ResourceId).Tags
            foreach ($key in $g.Tags.Keys)
            {
                if ($resourcetags.ContainsKey($key)) { $resourcetags.Remove($key) }
            }
            $resourcetags += $g.Tags
            Set-AzureRmResource -Tag $resourcetags -ResourceId $r.ResourceId -Force
        }
    }
}

To remove all tags, pass an empty hash table.

Set-AzureRmResourceGroup -Tag @{} -Name TagTestGgroup

To get resource groups with a specific tag, use Find-AzureRmResourceGroup cmdlet.

(Find-AzureRmResourceGroup -Tag @{ Dept="Finance" }).Name 

To get all the resources with a particular tag and value, use the Find-AzureRmResource cmdlet.

(Find-AzureRmResource -TagName Dept -TagValue Finance).Name

Azure CLI 2.0

With Azure CLI 2.0, you can add tags to resources and resource group, and query resources by tag values.

Every time you apply tags to a resource or resource group, you overwrite the existing tags on that resource or resource group. Therefore, you must use a different approach based on whether the resource or resource group has existing tags that you want to preserve. To add tags to a:

  • resource group without existing tags.

    az group update -n TagTestGroup --set tags.Environment=Test tags.Dept=IT
    
  • resource without existing tags.

    az resource tag --tags Dept=IT Environment=Test -g TagTestGroup -n storageexample --resource-type "Microsoft.Storage/storageAccounts"
    

To add tags to a resource that already has tags, first retrieve the existing tags:

az resource show --query tags --output list -g TagTestGroup -n storageexample --resource-type "Microsoft.Storage/storageAccounts"

Which returns the following format:

Dept        : Finance
Environment : Test

Reapply the existing tags to the resource, and add the new tags.

az resource tag --tags Dept=Finance Environment=Test CostCenter=IT -g TagTestGroup -n storageexample --resource-type "Microsoft.Storage/storageAccounts"

To get resource groups with a specific tag, use az group list.

az group list --tag Dept=IT

To get all the resources with a particular tag and value, use az resource list.

az resource list --tag Dept=Finance

Azure CLI 1.0

To add a tag to a resource group, use azure group set. If the resource group does not have any existing tags, pass in the tag.

azure group set -n tag-demo-group -t Dept=Finance

Tags are updated as a whole. If you want to add a tag to a resource group that has existing tags, pass all the tags.

azure group set -n tag-demo-group -t Dept=Finance;Environment=Production;Project=Upgrade

Tags are not inherited by resources in a resource group. To add a tag to a resource, use azure resource set. Pass the API version number for the resource type that you are adding the tag to. If you need to retrieve the API version, use the following command with the resource provider for the type you are setting:

azure provider show -n Microsoft.Storage --json

In the results, look for the resource type you want.

"resourceTypes": [
{
  "resourceType": "storageAccounts",
  ...
  "apiVersions": [
    "2016-01-01",
    "2015-06-15",
    "2015-05-01-preview"
  ]
}
...

Now, provide that API version, resource group name, resource name, resource type, and tag value as parameters.

azure resource set -g tag-demo-group -n storagetagdemo -r Microsoft.Storage/storageAccounts -t Dept=Finance -o 2016-01-01

Tags exist directly on resources and resource groups. To see the existing tags, get a resource group and its resources with azure group show.

azure group show -n tag-demo-group --json

Which returns metadata about the resource group, including any tags applied to it.

{
  "id": "/subscriptions/4705409c-9372-42f0-914c-64a504530837/resourceGroups/tag-demo-group",
  "name": "tag-demo-group",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "location": "southcentralus",
  "tags": {
    "Dept": "Finance",
    "Environment": "Production",
    "Project": "Upgrade"
  },
  ...
}

You view the tags for a particular resource by using azure resource show.

azure resource show -g tag-demo-group -n storagetagdemo -r Microsoft.Storage/storageAccounts -o 2016-01-01 --json

To retrieve all the resources with a tag value, use:

azure resource list -t Dept=Finance --json

To retrieve all the resource groups with a tag value, use:

azure group list -t Dept=Finance

You can view the existing tags in your subscription with the following command:

azure tag list

REST API

The portal and PowerShell both use the Resource Manager REST API behind the scenes. If you need to integrate tagging into another environment, you can get tags with a GET on the resource id and update the set of tags with a PATCH call.

Tags and billing

Tags enable you to group your billing data. For example, if you are running multiple VMs for different organizations, use the tags to group usage by cost center. You can also use tags to categorize costs by runtime environment; such as, the billing usage for VMs running in production environment.

You can retrieve information about tags through the Azure Resource Usage and RateCard APIs or the usage comma-separated values (CSV) file. You download the usage file from the Azure accounts portal or EA portal. For more information about programmatic access to billing information, see Gain insights into your Microsoft Azure resource consumption. For REST API operations, see Azure Billing REST API Reference.

When you download the usage CSV for services that support tags with billing, the tags appear in the Tags column. For more information, see Understand your bill for Microsoft Azure.

See tags in billing

Next Steps