- Article
- 12/09/2022
- 16 minutes to read
In this article
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.
Warning
Tags are stored as plain text. Never add sensitive values to tags. Sensitive values could be exposed through many methods, including cost reports, commands that return existing tag definitions, deployment histories, exported templates, and monitoring logs.
Important
Tag names are case-insensitive for operations. A tag with a tag name, regardless of the casing, is updated or retrieved. However, the resource provider might keep the casing you provide for the tag name. You’ll see that casing in cost reports.
Tag values are case-sensitive.
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 demoGroup New-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 demoGroup New-AzTag -ResourceId $resourceGroup.ResourceId -tag $tags
To update the tags for a resource group, use:
$tags = @{“CostCenter”=”00123”; “Environment”=”Production”} $resourceGroup = Get-AzResourceGroup -Name demoGroup Update-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”).Id New-AzTag -ResourceId “/subscriptions/$subscription” -Tag $tags
To update the tags for a subscription, use:
$tags = @{“Team”=”Web Apps”} $subscription = (Get-AzSubscription -SubscriptionName “Example Subscription”).Id Update-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 demoGroup Get-AzTag -ResourceId $resource.id
To see the tags for a resource group, use:
$resourceGroup = Get-AzResourceGroup -Name demoGroup Get-AzTag -ResourceId $resourceGroup.ResourceId
To see the tags for a subscription, use:
$subscription = (Get-AzSubscription -SubscriptionName “Example Subscription”).Id Get-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”).Id Remove-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.
Note
The tags you apply through an ARM template or Bicep file overwrite any existing tags.
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”: {} } ] } param location string = resourceGroup().location param utcShort string = utcNow(‘d’) resource stgAccount ‘Microsoft.Storage/storageAccounts@2021-04-01’ = { name: ‘storage${uniqueString(resourceGroup().id)}’ location: location sku: { name: ‘Standard_LRS’ } kind: ‘Storage’ tags: { Dept: ‘Finance’ Environment: ‘Production’ LastDeployed: utcShort } }
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”: {} } ] } param location string = resourceGroup().location param tagValues object = { Dept: ‘Finance’ Environment: ‘Production’ } resource stgAccount ‘Microsoft.Storage/storageAccounts@2021-04-01’ = { name: ‘storage${uniqueString(resourceGroup().id)}’ location: location sku: { name: ‘Standard_LRS’ } kind: ‘Storage’ tags: tagValues }
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”: {} } ] } param location string = resourceGroup().location resource stgAccount ‘Microsoft.Storage/storageAccounts@2021-04-01’ = { name: ‘storage${uniqueString(resourceGroup().id)}’ location: location sku: { name: ‘Standard_LRS’ } kind: ‘Storage’ tags: { CostCenter: ‘{“Dept”:”Finance”,”Environment”:”Production”}’ } }
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”: {} } ] } param location string = resourceGroup().location resource stgAccount ‘Microsoft.Storage/storageAccounts@2021-04-01’ = { name: ‘storage${uniqueString(resourceGroup().id)}’ location: location sku: { name: ‘Standard_LRS’ } kind: ‘Storage’ tags: { Dept: resourceGroup().tags[‘Dept’] Environment: resourceGroup().tags[‘Environment’] } }
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’)]” } } } ] } param tagName string = ‘TeamName’ param tagValue string = ‘AppTeam1’ resource applyTags ‘Microsoft.Resources/tags@2021-04-01’ = { name: ‘default’ properties: { tags: { ‘${tagName}’: 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’)]” } } ] } targetScope = ‘subscription’ param tagObject object = { TeamName: ‘AppTeam1’ Dept: ‘Finance’ Environment: ‘Production’ } resource applyTags ‘Microsoft.Resources/tags@2021-04-01’ = { name: ‘default’ properties: { tags: tagObject } }
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.
-
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.
-
To add a tag, select Click here to add tags.
-
Provide a name and value.
-
Continue adding tags as needed. When done, select Save.
-
The tags are now displayed in the overview.
-
To add or delete a tag, select change.
-
To delete a tag, select the trash icon. Then, select Save.
To bulk assign tags to multiple resources:
-
From any list of resources, select the checkbox for the resources you want to assign the tag. Then, select Assign tags.
-
Add names and values. When done, select Save.
To view all resources with a tag:
-
On the Azure portal menu, search for tags. Select it from the available options.
-
Select the tag for viewing resources.
-
All resources with that tag are displayed.
REST API
To work with tags through the Azure REST API, use:
SDKs
For examples of applying tags with SDKs, see:
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.
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
-