Merge pull request #208924 from tfitzmac/0823templatespecs

add required permissions for template specs

Author: prmerger-automator[bot]

articles/azure-resource-manager/bicep/template-specs.md

@@ -2,12 +2,12 @@
 title: Create & deploy template specs in Bicep
 description: Describes how to create template specs in Bicep and share them with other users in your organization.
 ms.topic: conceptual
-ms.date: 02/01/2022
+ms.date: 08/23/2022
 ---
 
 # Azure Resource Manager template specs in Bicep
 
-A template spec is a resource type for storing an Azure Resource Manager template (ARM template) for later deployment. This resource type enables you to share ARM templates with other users in your organization. Just like any other Azure resource, you can use Azure role-based access control (Azure RBAC) to share the template spec. You can use Azure CLI or Azure PowerShell to create template specs by providing Bicep files. The Bicep files are transpiled into ARM JSON templates before they are stored. Currently, you can't import a Bicep file from the Azure portal to create a template spec resource.
+A template spec is a resource type for storing an Azure Resource Manager template (ARM template) for later deployment. This resource type enables you to share ARM templates with other users in your organization. Just like any other Azure resource, you can use Azure role-based access control (Azure RBAC) to share the template spec. You can use Azure CLI or Azure PowerShell to create template specs by providing Bicep files. The Bicep files are transpiled into ARM JSON templates before they're stored. Currently, you can't import a Bicep file from the Azure portal to create a template spec resource.
 
 [Microsoft.Resources/templateSpecs](/azure/templates/microsoft.resources/templatespecs) is the resource type for template specs. It consists of a main template and any number of linked templates. Azure securely stores template specs in resource groups. Both the main template and the linked templates must be in JSON. Template Specs support [versioning](#versioning).
 
@@ -29,6 +29,12 @@ When designing your deployment, always consider the lifecycle of the resources a
 
 To learn more about template specs, and for hands-on guidance, see [Publish libraries of reusable infrastructure code by using template specs](/learn/modules/arm-template-specs).
 
+## Required permissions
+
+To create a template spec, you need **write** access to `Microsoft.Resources/templateSpecs` and `Microsoft.Resources/templateSpecs/versions`.
+
+To deploy a template spec, you need **read** access to `Microsoft.Resources/templateSpecs` and `Microsoft.Resources/templateSpecs/versions`. You also need **write** access to any resources deployed by the template spec, and access to `Microsoft.Resources/deployments/*`.
+
 ## Why use template specs?
 
 Template specs provide the following benefits:
@@ -150,7 +156,7 @@ The JSON template embedded in the Bicep file needs to make these changes:
 * To access the parameters and variables defined in the Bicep file, you can directly use the parameter names and the variable names. To access the parameters and variables defined in `mainTemplate`, you still need to use the ARM JSON template syntax.  For example, **'name': '[parameters(\'storageAccountType\')]'**.
 * Use the Bicep syntax to call Bicep functions.  For example, **'location': resourceGroup().location**.
 
-The size of a template spec is limited to approximated 2 MB. If a template spec size exceeds the limit, you will get the **TemplateSpecTooLarge** error code. The error message says:
+The size of a template spec is limited to approximated 2 MB. If a template spec size exceeds the limit, you'll get the **TemplateSpecTooLarge** error code. The error message says:
 
 ```error
 The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.
@@ -325,7 +331,7 @@ When you create a template spec, you provide a version name for it. As you itera
 
 ## Use tags
 
-[Tags](../management/tag-resources.md) help you logically organize your resources. You can add tags to template specs by using Azure PowerShell and Azure CLI:
+[Tags](../management/tag-resources.md) help you logically organize your resources. You can add tags to template specs by using Azure PowerShell and Azure CLI. The following example shows how to specify tags when creating the template spec:
 
 # [PowerShell](#tab/azure-powershell)
 
@@ -353,6 +359,8 @@ az ts create \
 
 ---
 
+The next example shows how to apply tags when updating an existing template spec:
+
 # [PowerShell](#tab/azure-powershell)
 
 ```azurepowershell
@@ -379,17 +387,15 @@ az ts update \
 
 ---
 
-When creating or modifying a template spec with the version parameter specified, but without the tag/tags parameter:
-
-* If the template spec exists and has tags, but the version doesn't exist, the new version inherits the same tags as the existing template spec.
-
-When creating or modifying a template spec with both the tag/tags parameter and the version parameter specified:
-
-* If both the template spec and the version don't exist, the tags are added to both the new template spec and the new version.
-* If the template spec exists, but the version doesn't exist, the tags are only added to the new version.
-* If both the template spec and the version exist, the tags only apply to the version.
+Both the template and its versions can have tags. The tags are applied or inherited depending on the parameters you specify.
 
-When modifying a template with the tag/tags parameter specified but without the version parameter specified, the tags is only added to the template spec.
+| Template spec | Version | Version parameter | Tag parameter | Tag values |
+| ------------- | ------- | ----------------- | ------------- | --------------- |
+| Exists      | N/A | Not specified     | Specified     | applied to the template spec   |
+| Exists      | New | Specified       | Not specified   | inherited from the template spec to the version |
+| New         | New | Specified       | Specified       | applied to both template spec and version |
+| Exists      | New | Specified       | Specified       | applied to the version |
+| Exists      | Exists | Specified    | Specified       | applied to the version |
 
 ## Link to template specs