Tag resources, resource groups, and subscriptions for logical organization - Azure Resource Manager (2023)

Tags are metadata elements that you apply to your Azure resources. They're key-value pairs that help you identify resources based on settings that are relevant to your organization. If you want to track the deployment environment for your resources, add a key named Environment. To identify the resources deployed to production, give them a value of Production. Fully formed, the key-value pair becomes, Environment = Production.

You can apply tags to your Azure resources, resource groups, and subscriptions.

For recommendations on how to implement a tagging strategy, see Resource naming and tagging decision guide.

Resource tags support all cost-accruing services. To ensure that cost-accruing services are provisioned with a tag, use one of the tag policies.

Required access

There are two ways to get the required access to tag resources.

• You can have write access to the Microsoft.Resources/tags resource type. This access lets you tag any resource, even if you don't have access to the resource itself. The Tag Contributor role grants this access. The tag contributor role, for example, can't apply tags to resources or resource groups through the portal. It can, however, apply tags to subscriptions through the portal. It supports all tag operations through Azure PowerShell and REST API.

• You can have write access to the resource itself. The Contributor role grants the required access to apply tags to any entity. To apply tags to only one resource type, use the contributor role for that resource. To apply tags to virtual machines, for example, use the Virtual Machine Contributor.

PowerShell

Apply tags

Azure PowerShell offers two commands to apply tags: New-AzTag and Update-AzTag. You need to have the Az.Resources module 1.12.0 version or later. You can check your version with Get-InstalledModule -Name Az.Resources. You can install that module or install Azure PowerShell version 3.6.1 or later.

The New-AzTag replaces all tags on the resource, resource group, or subscription. When you call the command, pass the resource ID of the entity you want to tag.

The following example applies a set of tags to a storage account:

$tags = @{"Dept"="Finance"; "Status"="Normal"}$resource = Get-AzResource -Name demoStorage -ResourceGroup demoGroupNew-AzTag -ResourceId $resource.id -Tag $tags

When the command completes, notice that the resource has two tags.

Properties : Name Value ====== ======= Dept Finance Status Normal

If you run the command again, but this time with different tags, notice that the earlier tags disappear.

$tags = @{"Team"="Compliance"; "Environment"="Production"}New-AzTag -ResourceId $resource.id -Tag $tags

Properties : Name Value =========== ========== Environment Production Team Compliance

To add tags to a resource that already has tags, use Update-AzTag. Set the -Operation parameter to Merge.

$tags = @{"Dept"="Finance"; "Status"="Normal"}Update-AzTag -ResourceId $resource.id -Tag $tags -Operation Merge

Notice that the existing tags grow with the addition of the two new tags.

Properties : Name Value =========== ========== Status Normal Dept Finance Team Compliance Environment Production

Each tag name can have only one value. If you provide a new value for a tag, it replaces the old value even if you use the merge operation. The following example changes the Status tag from Normal to Green.

$tags = @{"Status"="Green"}Update-AzTag -ResourceId $resource.id -Tag $tags -Operation Merge

Properties : Name Value =========== ========== Status Green Dept Finance Team Compliance Environment Production

When you set the -Operation parameter to Replace, the new set of tags replaces the existing tags.

$tags = @{"Project"="ECommerce"; "CostCenter"="00123"; "Team"="Web"}Update-AzTag -ResourceId $resource.id -Tag $tags -Operation Replace

Only the new tags remain on the resource.

Properties : Name Value ========== ========= CostCenter 00123 Team Web Project ECommerce

The same commands also work with resource groups or subscriptions. Pass them in the identifier of the resource group or subscription you want to tag.

To add a new set of tags to a resource group, use:

$tags = @{"Dept"="Finance"; "Status"="Normal"}$resourceGroup = Get-AzResourceGroup -Name demoGroupNew-AzTag -ResourceId $resourceGroup.ResourceId -tag $tags

To update the tags for a resource group, use:

$tags = @{"CostCenter"="00123"; "Environment"="Production"}$resourceGroup = Get-AzResourceGroup -Name demoGroupUpdate-AzTag -ResourceId $resourceGroup.ResourceId -Tag $tags -Operation Merge

To add a new set of tags to a subscription, use:

$tags = @{"CostCenter"="00123"; "Environment"="Dev"}$subscription = (Get-AzSubscription -SubscriptionName "Example Subscription").IdNew-AzTag -ResourceId "/subscriptions/$subscription" -Tag $tags

To update the tags for a subscription, use:

$tags = @{"Team"="Web Apps"}$subscription = (Get-AzSubscription -SubscriptionName "Example Subscription").IdUpdate-AzTag -ResourceId "/subscriptions/$subscription" -Tag $tags -Operation Merge

You may have more than one resource with the same name in a resource group. In that case, you can set each resource with the following commands:

$resource = Get-AzResource -ResourceName sqlDatabase1 -ResourceGroupName examplegroup$resource | ForEach-Object { Update-AzTag -Tag @{ "Dept"="IT"; "Environment"="Test" } -ResourceId $_.ResourceId -Operation Merge }

List tags

To get the tags for a resource, resource group, or subscription, use the Get-AzTag command and pass the resource ID of the entity.

To see the tags for a resource, use:

$resource = Get-AzResource -Name demoStorage -ResourceGroup demoGroupGet-AzTag -ResourceId $resource.id

To see the tags for a resource group, use:

$resourceGroup = Get-AzResourceGroup -Name demoGroupGet-AzTag -ResourceId $resourceGroup.ResourceId

To see the tags for a subscription, use:

$subscription = (Get-AzSubscription -SubscriptionName "Example Subscription").IdGet-AzTag -ResourceId "/subscriptions/$subscription"

List by tag

To get resources that have a specific tag name and value, use:

(Get-AzResource -Tag @{ "CostCenter"="00123"}).Name

To get resources that have a specific tag name with any tag value, use:

(Get-AzResource -TagName "Dept").Name

To get resource groups that have a specific tag name and value, use:

(Get-AzResourceGroup -Tag @{ "CostCenter"="00123" }).ResourceGroupName

Remove tags

To remove specific tags, use Update-AzTag and set -Operation to Delete. Pass the resource IDs of the tags you want to delete.

$removeTags = @{"Project"="ECommerce"; "Team"="Web"}Update-AzTag -ResourceId $resource.id -Tag $removeTags -Operation Delete

The specified tags are removed.

Properties : Name Value ========== ===== CostCenter 00123

To remove all tags, use the Remove-AzTag command.

$subscription = (Get-AzSubscription -SubscriptionName "Example Subscription").IdRemove-AzTag -ResourceId "/subscriptions/$subscription"

Azure CLI

Apply tags

Azure CLI offers two commands to apply tags: az tag create and az tag update. You need to have the Azure CLI 2.10.0 version or later. You can check your version with az version. To update or install it, see Install the Azure CLI.

The az tag create replaces all tags on the resource, resource group, or subscription. When you call the command, pass the resource ID of the entity you want to tag.

The following example applies a set of tags to a storage account:

resource=$(az resource show -g demoGroup -n demoStorage --resource-type Microsoft.Storage/storageAccounts --query "id" --output tsv)az tag create --resource-id $resource --tags Dept=Finance Status=Normal

When the command completes, notice that the resource has two tags.

"properties": { "tags": { "Dept": "Finance", "Status": "Normal" }},

If you run the command again, but this time with different tags, notice that the earlier tags disappear.

az tag create --resource-id $resource --tags Team=Compliance Environment=Production

"properties": { "tags": { "Environment": "Production", "Team": "Compliance" }},

To add tags to a resource that already has tags, use az tag update. Set the --operation parameter to Merge.

az tag update --resource-id $resource --operation Merge --tags Dept=Finance Status=Normal

Notice that the existing tags grow with the addition of the two new tags.

"properties": { "tags": { "Dept": "Finance", "Environment": "Production", "Status": "Normal", "Team": "Compliance" }},

Each tag name can have only one value. If you provide a new value for a tag, the new tag replaces the old value, even if you use the merge operation. The following example changes the Status tag from Normal to Green.

az tag update --resource-id $resource --operation Merge --tags Status=Green

"properties": { "tags": { "Dept": "Finance", "Environment": "Production", "Status": "Green", "Team": "Compliance" }},

When you set the --operation parameter to Replace, the new set of tags replaces the existing tags.

az tag update --resource-id $resource --operation Replace --tags Project=ECommerce CostCenter=00123 Team=Web

Only the new tags remain on the resource.

"properties": { "tags": { "CostCenter": "00123", "Project": "ECommerce", "Team": "Web" }},

The same commands also work with resource groups or subscriptions. Pass them in the identifier of the resource group or subscription you want to tag.

To add a new set of tags to a resource group, use:

group=$(az group show -n demoGroup --query id --output tsv)az tag create --resource-id $group --tags Dept=Finance Status=Normal

To update the tags for a resource group, use:

az tag update --resource-id $group --operation Merge --tags CostCenter=00123 Environment=Production

To add a new set of tags to a subscription, use:

sub=$(az account show --subscription "Demo Subscription" --query id --output tsv)az tag create --resource-id /subscriptions/$sub --tags CostCenter=00123 Environment=Dev

To update the tags for a subscription, use:

az tag update --resource-id /subscriptions/$sub --operation Merge --tags Team="Web Apps"

List tags

To get the tags for a resource, resource group, or subscription, use the az tag list command and pass the resource ID of the entity.

To see the tags for a resource, use:

resource=$(az resource show -g demoGroup -n demoStorage --resource-type Microsoft.Storage/storageAccounts --query "id" --output tsv)az tag list --resource-id $resource

To see the tags for a resource group, use:

group=$(az group show -n demoGroup --query id --output tsv)az tag list --resource-id $group

To see the tags for a subscription, use:

sub=$(az account show --subscription "Demo Subscription" --query id --output tsv)az tag list --resource-id /subscriptions/$sub

List by tag

To get resources that have a specific tag name and value, use:

az resource list --tag CostCenter=00123 --query [].name

To get resources that have a specific tag name with any tag value, use:

az resource list --tag Team --query [].name

To get resource groups that have a specific tag name and value, use:

az group list --tag Dept=Finance

Remove tags

To remove specific tags, use az tag update and set --operation to Delete. Pass the resource ID of the tags you want to delete.

az tag update --resource-id $resource --operation Delete --tags Project=ECommerce Team=Web

You've removed the specified tags.

"properties": { "tags": { "CostCenter": "00123" }},

To remove all tags, use the az tag delete command.

az tag delete --resource-id $resource

Handling spaces

If your tag names or values include spaces, enclose them in quotation marks.

az tag update --resource-id $group --operation Merge --tags "Cost Center"=Finance-1222 Location="West US"

ARM templates

You can tag resources, resource groups, and subscriptions during deployment with an ARM template.

Apply values

The following example deploys a storage account with three tags. Two of the tags (Dept and Environment) are set to literal values. One tag (LastDeployed) is set to a parameter that defaults to the current date.

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

Apply an object

You can define an object parameter that stores several tags and apply that object to the tag element. This approach provides more flexibility than the previous example because the object can have different properties. Each property in the object becomes a separate tag for the resource. The following example has a parameter named tagValues that's applied to the tag element.

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

Apply a JSON string

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 can't 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/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "location": { "type": "string", "defaultValue": "[resourceGroup().location]" } }, "resources": [ { "type": "Microsoft.Storage/storageAccounts", "apiVersion": "2021-04-01", "name": "[concat('storage', uniqueString(resourceGroup().id))]", "location": "[parameters('location')]", "sku": { "name": "Standard_LRS" }, "kind": "Storage", "tags": { "CostCenter": "{\"Dept\":\"Finance\",\"Environment\":\"Production\"}" }, "properties": {} } ]}

Apply tags from resource group

To apply tags from a resource group to a resource, use the resourceGroup() function. When you get the tag value, use the tags[tag-name] syntax instead of the tags.tag-name syntax, because some characters aren't parsed correctly in the dot notation.

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

Apply tags to resource groups or subscriptions

You can add tags to a resource group or subscription by deploying the Microsoft.Resources/tags resource type. You can apply the tags to the target resource group or subscription you want to deploy. Each time you deploy the template you replace any previous tags.

{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "tagName": { "type": "string", "defaultValue": "TeamName" }, "tagValue": { "type": "string", "defaultValue": "AppTeam1" } }, "resources": [ { "type": "Microsoft.Resources/tags", "name": "default", "apiVersion": "2021-04-01", "properties": { "tags": { "[parameters('tagName')]": "[parameters('tagValue')]" } } } ]}

To apply the tags to a resource group, use either Azure PowerShell or Azure CLI. Deploy to the resource group that you want to tag.

New-AzResourceGroupDeployment -ResourceGroupName exampleGroup -TemplateFile https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/tags.json

az deployment group create --resource-group exampleGroup --template-uri https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/tags.json

To apply the tags to a subscription, use either PowerShell or Azure CLI. Deploy to the subscription that you want to tag.

New-AzSubscriptionDeployment -name tagresourcegroup -Location westus2 -TemplateUri https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/tags.json

az deployment sub create --name tagresourcegroup --location westus2 --template-uri https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/tags.json

For more information about subscription deployments, see Create resource groups and resources at the subscription level.

The following template adds the tags from an object to either a resource group or subscription.

{ "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "tags": { "type": "object", "defaultValue": { "TeamName": "AppTeam1", "Dept": "Finance", "Environment": "Production" } } }, "resources": [ { "type": "Microsoft.Resources/tags", "apiVersion": "2021-04-01", "name": "default", "properties": { "tags": "[parameters('tags')]" } } ]}

Portal

If a user doesn't have the required access for applying tags, you can assign the Tag Contributor role to the user. For more information, see Tutorial: Grant a user access to Azure resources using RBAC and the Azure portal.

1. To view the tags for a resource or a resource group, look for existing tags in the overview. If you have not previously applied tags, the list is empty.

   

2. To add a tag, select Click here to add tags.

3. Provide a name and value.

   

4. Continue adding tags as needed. When done, select Save.

   

5. The tags are now displayed in the overview.

   

6. To add or delete a tag, select change.

7. To delete a tag, select the trash icon. Then, select Save.

   

To bulk assign tags to multiple resources:

1. From any list of resources, select the checkbox for the resources you want to assign the tag. Then, select Assign tags.

   

2. Add names and values. When done, select Save.

   

To view all resources with a tag:

1. On the Azure portal menu, search for tags. Select it from the available options.

   

2. Select the tag for viewing resources.

   

3. All resources with that tag are displayed.

   

REST API

To work with tags through the Azure REST API, use:

• Tags - Create Or Update At Scope (PUT operation)
• Tags - Update At Scope (PATCH operation)
• Tags - Get At Scope (GET operation)
• Tags - Delete At Scope (DELETE operation)

SDKs

For examples of applying tags with SDKs, see:

• .NET
• Java
• JavaScript
• Python

Resources don't inherit the tags you apply to a resource group or a subscription. To apply tags from a subscription or resource group to the resources, see Azure Policies - tags.

Tags and billing

You can use tags to group your billing data. If you're running multiple VMs for different organizations, for example, 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 the production environment.

You can retrieve information about tags by downloading the usage file available from the Azure portal. For more information, see Download or view your Azure billing invoice and daily usage data. For services that support tags with billing, the tags appear in the Tags column.

For REST API operations, see Azure Billing REST API Reference.

Limitations

The following limitations apply to tags:

• Not all resource types support tags. To determine if you can apply a tag to a resource type, see Tag support for Azure resources.

• Each resource, resource group, and subscription can have a maximum of 50 tag name-value pairs. If you need to apply more tags than the maximum allowed number, use a JSON string for the tag value. The JSON string can contain many of the values that you apply to a single tag name. A resource group or subscription can contain many resources that each have 50 tag name-value pairs.

• The tag name has a limit of 512 characters and the tag value has a limit of 256 characters. For storage accounts, the tag name has a limit of 128 characters and the tag value has a limit of 256 characters.

• Classic resources such as Cloud Services don't support tags.

• Azure IP Groups and Azure Firewall Policies don't support PATCH operations. PATCH API method operations, therefore, can't update tags through the portal. Instead, you can use the update commands for those resources. You can update tags for an IP group, for example, with the az network ip-group update command.

• Tag names can't contain these characters: <, >, %, &, \, ?, /

  Note

  • Azure Domain Name System (DNS) zones don't support the use of spaces in the tag or a tag that starts with a number. Azure DNS tag names don't support special and unicode characters. The value can contain all characters.

  • Traffic Manager doesn't support the use of spaces, # or : in the tag name. The tag name can't start with a number.

  • Azure Front Door doesn't support the use of # or : in the tag name.

  • The following Azure resources only support 15 tags:

    • Azure Automation
    • Azure Content Delivery Network (CDN)
    • Azure DNS (Zone and A records)
    • Azure Log Analytics Saved Search

Next steps

• Not all resource types support tags. To determine if you can apply a tag to a resource type, see Tag support for Azure resources.
• For recommendations on how to implement a tagging strategy, see Resource naming and tagging decision guide.