ARM Template Specs now GA!

TL;DR – Template Specs is a new resource type for storing ARM templates in your resource groups for faster sharing, deployment, and role-based access control (RBAC) on those Templates shared within an organization. Template Specs addresses today's biggest challenges around ARM template management, storage, and access.

The Problem: Sharing ARM templates across an organization is challenging, requiring more management steps of the external or internal storage from which they are shared.

• Sharing: ensuring the right teams within your organization have access becomes very tedious as you cannot leverage Azure RBAC on the ARM templates you want to share.
• Management: providing teams with the latest ARM templates in a consistent and versioned way.

Why Template Specs?

As a native solution, Template Specs will enable users to bring all their ARM templates to Azure as a resource and securely store and share them within an Azure tenant.

The Solution: 1st Party secure storage and management of ARM templates within Azure.

• Sharing: Who can access a Template Spec can be defined using Azure RBAC.
• Management: Template Specs can be versioned within the same resource, ensuring users can always access the latest iterations of an ARM template (or templates) stored in a Template Spec.

What's New Since Public Preview?

New API version 2021-05-01. Thanks to all the customer feedback during our public preview, we were able to close 3 issues, fix 5 bugs, and make the decision to change the names of the template and artifacts properties:

What's Coming Soon Post-GA?

• Bicep integration: az ts create with bicep files.
• Built-in template specs support.
• Support for UI Forms – UI Forms will replace createUIDefinition going forward.
• GA version of Azure CLI and PowerShell with breaking changes being released by end of May.
  • Due to the property renames highlighted above, you will see new property names when you GET a Template Spec version. This could be a breaking change if you are dependent on querying these properties in a script. This will not change how Template Specs are created or updated when using Azure Portal, Azure CLI, and PowerShell, but it will change how they are created via REST/ARM Templates/Bicep.
  • If you’d like to test the latest Az PowerShell cmdlets early, they are available in PowerShell Gallery

Template Spec Reference and Docs:

• Template specs overview - Microsoft Docs
• Create a template spec with linked templates - Microsoft Docs
• Deploy a template spec as a linked template - Microsoft Docs
• Link templates for deployment - Microsoft Docs
• Convert portal template to template spec - Microsoft Docs

Note: Template Specs can be created with an ARM template, but we strongly recommend using Portal, PowerShell or CLI for creating Template Specs. Microsoft.Resources/templateSpecs/versions - ARM template reference | Microsoft Docs

Creating and Deploying a Template Spec Resource

A Template Spec is a resource that contains an array of Template Spec versions which consists of a root template and any number of linked templates. A Template Spec can be created using the Portal, PowerShell, Azure CLI, REST API, or ARM Template. To help visualize a Template Spec create, here are some examples of what it would look like in the Azure CLI:

Creating a Template Spec using Azure CLI
To create a Template Spec, use the az ts create command to package an ARM into the Template Spec resource.

az ts create --name webAppSpec --version "v1.0" --resource-group rgName --location "westus2" --template-file "azuredeploy.json"

Required properties:

• --name: The name for the Template Spec resource.
• --version: The version number or name of the version being + created.
• --location: The Azure region for the Template Spec resource.
• --template-file: The ARM template to be packaged into a template spec.

Creating and Deploying a Template Spec with Linked Templates using Azure CLI
To create a Template Spec with artifacts inside it, we need the following:

1. Create main template (e.g. azuredeploy.json) that deploys linked templates, to be passed into the az ts create command as a template file.

2. Create N number of deployment resources with linked templates referenced using the relativePath property within the templateLink object.
   
   In this example the linked templates are stored in a subfolder called linkedTemplates, which is in the same path as the main template file. The relativePath property is relative to the template file where relativePath is declared. The relativePath property can take any of the following values:
   ./linkedTemplates/storagelinkedTemplate.json
/linkedTemplates/storagelinkedTemplate.json
linkedTemplates/storagelinkedTemplate.json
   Note: relativePath can also be used deploy remote linked templates given all template files are staged together and available via remote URI, such as GitHub or Azure storage. The main template is called by using URI and all linked templates referenced as relative to that main template will have a URI constructed using the main template URI and the relativePath specified. This feature requires api version 2020-10-01 or greater. To learn more about this feature, please refer to Link templates for deployment - Microsoft Docs.

3. Run the az ts create command to create or update a template spec version. This command packages the linked templates added via templateLink as linked templates in your Template Spec version.
   az ts create --name webAppSpec --version "v1.0" --resource-group rgName --location "westus2" --template-file "azuredeploy.json"
   This command packages the template file azuredeploy.json into the main template of the Template Spec version webAppSpec-v1.0 and all linked templates specified into the linkedTemplates[] array of the Template Spec object.

4. Deploy the Template Spec by passing in its resource ID using the az deployment group create command. First, we need to get the ID of the Template Spec resource created, and this can be done easily in the Azure CLI by using the az ts show command:
   id=$(az ts show --name webAppSpec --version "v1.0" --resource-group rgName --query "id")
   After storing the resource ID of the template spec into a variable, run the command az deployment group create and pass in the variable to the --template-spec input parameter:
   az deployment group create --resource-group rgName --template-spec $id

5. Verify the contents of a Template Spec by running the az ts export command that downloads a specified Template Spec version into an --output-folder in your local file system.
   az ts export --output-folder "C:\\exported-template-specs" -s "template-spec-version-ID"
   This command exports the specified Template Spec’s main template (e.g. webAppSpec.JSON) and an artifacts folder with all of its corresponding linked templates.
   
   The contents of a Template Spec version can also be seen using the Azure Portal.
   

Deploying a Template Spec as Linked Template using ARM Template with ID Reference

A Template Spec resource can also be referenced using the templateLink property and specifying the id of the template spec:

Template Specs in National Clouds
Please note that Template Specs is not yet GA in National Clouds. The target GA date for National Clouds is end of July.

References and Docs

• Template Spec CLI reference
• Template Spec ARM reference
• Template Spec PowerShell reference
• Template Spec REST API reference
• Template Spec Quick Start Tutorial
• Template specs overview - Microsoft Docs
• Create a template spec with linked templates - Microsoft Docs
• Deploy a template spec as a linked template - Microsoft Docs
• Link templates for deployment - Microsoft Docs