Skip to content

Commit 54e9185

Browse files
tfitzmactfitzmac
committed
update tags for new PowerShell commands
1 parent 602cd57 commit 54e9185

File tree

3 files changed

+166
-51
lines changed

3 files changed

+166
-51
lines changed

‎articles/azure-resource-manager/management/tag-policies.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Policies for tagging resources
3+
description: Describes the Azure Policies that you can assign to ensure tag compliance.
4+
ms.topic: conceptual
5+
ms.date: 03/18/2020
6+
---
7+
8+
# Assign policies for tag compliance
9+
10+
You can use [Azure Policy](../../governance/policy/overview.md) to enforce tagging rules and conventions. By creating a policy, you avoid the scenario of resources being deployed to your subscription that don't comply with the expected tags for your organization. Instead of manually applying tags or searching for resources that aren't compliant, you can create a policy that automatically applies the needed tags during deployment. Tags can also now be applied to existing resources with the new [Modify](../../governance/policy/concepts/effects.md#modify) effect and a [remediation task](../../governance/policy/how-to/remediate-resources.md). The following section shows example policies for tags.
11+
12+
## Policies
13+
14+
[!INCLUDE [Tag policies](../../../includes/azure-policy-samples-policies-tags.md)]
15+
16+
## Next steps
17+
18+
* To learn about tagging resources, see [Use tags to organize your Azure resources](tag-resources.md).
19+
* Not all resource types support tags. To determine if you can apply a tag to a resource type, see [Tag support for Azure resources](tag-support.md).

‎articles/azure-resource-manager/management/tag-resources.md

Lines changed: 143 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,135 @@
11
---
2-
title: Tag resources for logical organization
2+
title: Tag resources, resource groups, and subscriptions for logical organization
33
description: Shows how to apply tags to organize Azure resources for billing and managing.
44
ms.topic: conceptual
5-
ms.date: 01/03/2020
5+
ms.date: 03/18/2020
66
---
7-
# Use tags to organize your Azure resources
7+
# Use tags to organize your Azure resources, resource groups and subscriptions
88

9-
You apply tags to your Azure resources to logically organize them into a taxonomy. Each tag consists of a name and a value pair. For example, you can apply the name "Environment" and the value "Production" to all the resources in production.
9+
You apply tags to your Azure resources, resource groups, and subscriptions to logically organize them into a taxonomy. Each tag consists of a name and a value pair. For example, you can apply the name "Environment" and the value "Production" to all the resources in production.
1010

11-
After you apply tags, you can retrieve all the resources in your subscription with that tag name and value. Tags enable you to retrieve related resources from different resource groups. This approach is helpful when you need to organize resources for billing or management.
11+
For recommendations on how to implement a tagging strategy, see [Resource naming and tagging decision guide](/azure/cloud-adoption-framework/decision-guides/resource-tagging/?toc=/azure/azure-resource-manager/management/toc.json).
1212

13-
Your taxonomy should consider a self-service metadata tagging strategy in addition to an autotagging strategy to reduce the burden on users and increase accuracy.
13+
You can apply Azure Policies to make sure tagging conventions are maintained for your organization. For more information, see [Assign policies for tag compliance](tag-policies.md).
1414

1515
[!INCLUDE [Handle personal data](../../../includes/gdpr-intro-sentence.md)]
1616

17-
## Limitations
17+
## Required access
1818

19-
The following limitations apply to tags:
19+
To apply tags to resources, the user must have write access to that resource type. To apply tags to all resource types, use the [Contributor](../../role-based-access-control/built-in-roles.md#contributor) role. To apply tags to only one resource type, use the contributor role for that resource. For example, to apply tags to virtual machines, use the [Virtual Machine Contributor](../../role-based-access-control/built-in-roles.md#virtual-machine-contributor).
2020

21-
* Not all resource types support tags. To determine if you can apply a tag to a resource type, see [Tag support for Azure resources](tag-support.md).
22-
* Each resource or resource group 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 values that are applied to a single tag name. A resource group can contain many resources that each have 50 tag name/value pairs.
23-
* The tag name is limited to 512 characters, and the tag value is limited to 256 characters. For storage accounts, the tag name is limited to 128 characters, and the tag value is limited to 256 characters.
24-
* Generalized VMs don't support tags.
25-
* Tags applied to the resource group are not inherited by the resources in that resource group.
26-
* Tags can't be applied to classic resources such as Cloud Services.
27-
* Tag names can't contain these characters: `<`, `>`, `%`, `&`, `\`, `?`, `/`
21+
## PowerShell
2822

29-
> [!NOTE]
30-
> Currently Azure DNS zones and Traffic Manger services also don't allow the use of spaces in the tag.
23+
Azure PowerShell offers two commands for applying tags - [New-AzTag](/powershell/module/az.resources/new-aztag) and [Update-AzTag](/powershell/module/az.resources/update-aztag). You must have Azure PowerShell 3.6.1 or later to use these commands.
3124

32-
## Required access
25+
The **New-AzTag** replaces all tags on the resource, resource group, or subscription. When calling the command, pass in the resource ID of the entity you wish to tag.
3326

34-
To apply tags to resources, the user must have write access to that resource type. To apply tags to all resource types, use the [Contributor](../../role-based-access-control/built-in-roles.md#contributor) role. To apply tags to only one resource type, use the contributor role for that resource. For example, to apply tags to virtual machines, use the [Virtual Machine Contributor](../../role-based-access-control/built-in-roles.md#virtual-machine-contributor).
27+
The following example applies a set of tags to a storage account:
3528

36-
## Policies
29+
```azurepowershell-interactive
30+
$tags = @{"Dept"="Finance"; "Status"="Normal"}
31+
$resource = Get-AzResource -resourcename demoStorage -resourcegroup demoGroup
32+
New-AzTag -ResourceId $resource.id -Tag $tags
33+
```
3734

38-
You can use [Azure Policy](../../governance/policy/overview.md) to enforce tagging rules and conventions. By creating a policy, you avoid the scenario of resources being deployed to your subscription that don't comply with the expected tags for your organization. Instead of manually applying tags or searching for resources that aren't compliant, you can create a policy that automatically applies the needed tags during deployment. Tags can also now be applied to existing resources with the new [Modify](../../governance/policy/concepts/effects.md#modify) effect and a [remediation task](../../governance/policy/how-to/remediate-resources.md). The following section shows example policies for tags.
35+
When the command completes, notice that the resource has two tags.
3936

40-
[!INCLUDE [Tag policies](../../../includes/azure-policy-samples-policies-tags.md)]
37+
```azurepowershell
38+
Properties :
39+
Name Value
40+
====== =======
41+
Dept Finance
42+
Status Normal
43+
```
4144

42-
## PowerShell
45+
If you run the command again but this time with different tags, notice that the earlier tags are removed.
46+
47+
```azurepowershell-interactive
48+
$tags = @{"Team"="Compliance"; "Environment"="Production"}
49+
New-AzTag -ResourceId $resource.id -Tag $tags
50+
```
51+
52+
```azurepowershell
53+
Properties :
54+
Name Value
55+
=========== ==========
56+
Environment Production
57+
Team Compliance
58+
```
59+
60+
To add tags to a resource that already has tags, use **Update-AzTag**. Set the **-Operation** parameter to **Merge**.
61+
62+
```azurepowershell-interactive
63+
$tags = @{"Dept"="Finance"; "Status"="Normal"}
64+
Update-AzTag -ResourceId $resource.id -Tag $tags -Operation Merge
65+
```
66+
67+
Notice all four tags have been applied to the resource.
68+
69+
```azurepowershell
70+
Properties :
71+
Name Value
72+
=========== ==========
73+
Status Normal
74+
Dept Finance
75+
Team Compliance
76+
Environment Production
77+
```
78+
79+
When you set the **-Operation** parameter to **Replace**, the existing tags are replaced by the new set of tags.
80+
81+
```azurepowershell-interactive
82+
$tags = @{"Project"="ECommerce"; "CostCenter"="00123"}
83+
Update-AzTag -ResourceId $resource.id -Tag $tags -Operation Replace
84+
```
85+
86+
Only the new tags remain on the resource.
87+
88+
```azurepowershell
89+
Properties :
90+
Name Value
91+
========== =========
92+
CostCenter 00123
93+
Project ECommerce
94+
```
95+
96+
You can also set **-Operation** to **Delete** to remove a specific tag.
97+
98+
```azurepowershell-interactive
99+
$removeTags = @{"Project"="ECommerce"}
100+
Update-AzTag -ResourceId $resource.id -Tag $removeTags -Operation Delete
101+
```
102+
103+
The specified tag is removed.
104+
105+
```azurepowershell
106+
Properties :
107+
Name Value
108+
========== =====
109+
CostCenter 00123
110+
```
111+
112+
To add tags to a *resource without existing tags*, use:
113+
114+
```azurepowershell-interactive
115+
$resource = Get-AzResource -ResourceName examplevnet -ResourceGroupName examplegroup
116+
Set-AzResource -Tag @{ "Dept"="IT"; "Environment"="Test" } -ResourceId $resource.ResourceId -Force
117+
```
118+
119+
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:
120+
121+
```azurepowershell-interactive
122+
$resource = Get-AzResource -ResourceName sqlDatabase1 -ResourceGroupName examplegroup
123+
$resource | ForEach-Object { Set-AzResource -Tag @{ "Dept"="IT"; "Environment"="Test" } -ResourceId $_.ResourceId -Force }
124+
```
125+
126+
To add tags to a *resource that has existing tags*, use:
127+
128+
```azurepowershell-interactive
129+
$resource = Get-AzResource -ResourceName examplevnet -ResourceGroupName examplegroup
130+
$resource.Tags.Add("Status", "Approved")
131+
Set-AzResource -Tag $resource.Tags -ResourceId $resource.ResourceId -Force
132+
```
43133

44134
To see the existing tags for a *resource group*, use:
45135

@@ -68,12 +158,6 @@ Or, if you have the resource ID for a resource, you can pass that resource ID to
68158
(Get-AzResource -ResourceId /subscriptions/<subscription-id>/resourceGroups/<rg-name>/providers/Microsoft.Storage/storageAccounts/<storage-name>).Tags
69159
```
70160

71-
To get *resource groups that have a specific tag name and value*, use:
72-
73-
```azurepowershell-interactive
74-
(Get-AzResourceGroup -Tag @{ "Dept"="Finance" }).ResourceGroupName
75-
```
76-
77161
To get *resources that have a specific tag name and value*, use:
78162

79163
```azurepowershell-interactive
@@ -86,6 +170,18 @@ To get *resources that have a specific tag name*, use:
86170
(Get-AzResource -TagName "Dept").Name
87171
```
88172

173+
### Resource group
174+
175+
To get *resource groups that have a specific tag name and value*, use:
176+
177+
```azurepowershell-interactive
178+
(Get-AzResourceGroup -Tag @{ "Dept"="Finance" }).ResourceGroupName
179+
```
180+
181+
182+
183+
184+
89185
Every time you apply tags to a resource or a 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.
90186

91187
To add tags to a *resource group without existing tags*, use:
@@ -102,27 +198,7 @@ $tags.Add("Status", "Approved")
102198
Set-AzResourceGroup -Tag $tags -Name examplegroup
103199
```
104200

105-
To add tags to a *resource without existing tags*, use:
106201

107-
```azurepowershell-interactive
108-
$resource = Get-AzResource -ResourceName examplevnet -ResourceGroupName examplegroup
109-
Set-AzResource -Tag @{ "Dept"="IT"; "Environment"="Test" } -ResourceId $resource.ResourceId -Force
110-
```
111-
112-
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:
113-
114-
```azurepowershell-interactive
115-
$resource = Get-AzResource -ResourceName sqlDatabase1 -ResourceGroupName examplegroup
116-
$resource | ForEach-Object { Set-AzResource -Tag @{ "Dept"="IT"; "Environment"="Test" } -ResourceId $_.ResourceId -Force }
117-
```
118-
119-
To add tags to a *resource that has existing tags*, use:
120-
121-
```azurepowershell-interactive
122-
$resource = Get-AzResource -ResourceName examplevnet -ResourceGroupName examplegroup
123-
$resource.Tags.Add("Status", "Approved")
124-
Set-AzResource -Tag $resource.Tags -ResourceId $resource.ResourceId -Force
125-
```
126202

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

@@ -275,7 +351,7 @@ done
275351
IFS=$origIFS
276352
```
277353

278-
## Templates
354+
## ARM templates
279355

280356
To tag a resource during deployment, add the `tags` element to the resource you're deploying. Provide the tag name and value.
281357

@@ -436,7 +512,23 @@ You can retrieve information about tags through the [Azure Resource Usage and Ra
436512

437513
For REST API operations, see [Azure Billing REST API Reference](/rest/api/billing/).
438514

515+
## Limitations
516+
517+
The following limitations apply to tags:
518+
519+
* Not all resource types support tags. To determine if you can apply a tag to a resource type, see [Tag support for Azure resources](tag-support.md).
520+
* Each resource or resource group 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 values that are applied to a single tag name. A resource group can contain many resources that each have 50 tag name/value pairs.
521+
* The tag name is limited to 512 characters, and the tag value is limited to 256 characters. For storage accounts, the tag name is limited to 128 characters, and the tag value is limited to 256 characters.
522+
* Generalized VMs don't support tags.
523+
* Tags applied to the resource group are not inherited by the resources in that resource group.
524+
* Tags can't be applied to classic resources such as Cloud Services.
525+
* Tag names can't contain these characters: `<`, `>`, `%`, `&`, `\`, `?`, `/`
526+
527+
> [!NOTE]
528+
> Currently Azure DNS zones and Traffic Manger services also don't allow the use of spaces in the tag.
529+
530+
439531
## Next steps
440532

441533
* Not all resource types support tags. To determine if you can apply a tag to a resource type, see [Tag support for Azure resources](tag-support.md).
442-
* For an introduction to using the portal, see [Using the Azure portal to manage your Azure resources](manage-resource-groups-portal.md).
534+
* For an introduction to using the portal, see [Using the Azure portal to manage your Azure resources](manage-resource-groups-portal.md).

‎articles/azure-resource-manager/management/toc.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,8 +66,12 @@
6666
href: ../../virtual-network/move-across-regions-publicip-portal.md?toc=/azure/azure-resource-manager/toc.json
6767
- name: Tags
6868
items:
69+
- name: Decision guide
70+
href: /azure/cloud-adoption-framework/decision-guides/resource-tagging/?toc=/azure/azure-resource-manager/management/toc.json
6971
- name: Tag resources
7072
href: tag-resources.md
73+
- name: Policies
74+
href: tag-policies.md
7175
- name: Tag support
7276
href: tag-support.md
7377
- name: Manage resource groups

0 commit comments

Comments
 (0)