Apply tags with Azure PowerShell

  • Article

This article describes how to use Azure PowerShell to tag resources, resource groups, and subscriptions. For tag recommendations and limitations, see Use tags to organize your Azure resources and management hierarchy.

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"}
$resource = Get-AzResource -Name demostorage -ResourceGroup demoGroup
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"}
$resource = Get-AzResource -Name demostorage -ResourceGroup demoGroup
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"}
$resource = Get-AzResource -Name demostorage -ResourceGroup demoGroup
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"}
$resource = Get-AzResource -Name demostorage -ResourceGroup demoGroup
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"}
$resource = Get-AzResource -Name demostorage -ResourceGroup demoGroup
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"

Next steps