Create and Deploy ARM Templates is the second post in our getting started with ARM templates blog series.
In the first post we covered some of the basics of ARM Templates, specifically what they are and how to use them. So in this post, we are going look at how you can create and deploy them. Including how you can test and troubleshoot these deployments.
Create ARM Templates
Authoring Tools
The first thing that we need to do is pick our authoring tool for creating our templates. With this in mind, let’s see what options are available?
• Visual Studio – provides a rich set of features for creating and deploying ARM templates. In order to leverage these features we will need to install the Azure Resource Manager tools, under the Azure development components.
• VS Code – conversely, VS Code and the Azure Resource Manager (ARM) Tools extension offers a lightweight alternative to Visual Studio but lacks some of the quick start and deployment features so it is better suited to authors with experience.
VS Code – Azure Resource Manager (ARM) Tools.
Template Creation
Before you jump in and create an ARM template it is important to understand the different options available. Because some of these options are better suited to specific scenarios. For example if you are creating ARM templates for existing Azure resources. You might find it easier to export a template from the Azure Portal and customise it. Rather than building them from scratch.
Export Existing Resources
First and foremost you can export templates via the Azure Portal, Azure CLI or Azure PowerShell Module. Including at the resource or resource group level. Exporting at a resource group level includes all of the resources within the resource group. And as a result a single ARM template containing all of the resources is created. Because of this, if you have a lot of resources in your resource group it might be easier to export single resource at a time rather than all resources. Especially, if you are just getting started working with ARM Templates.
In order to export an individual resource via the Azure Portal, navigate to the resource that you wish to export and select Export Template from the left-hand navigation menu.
Azure Marketplace – Template deployment
In addition, the Template deployment (deploy using custom templates) extension from the Azure Marketplace gives you the ability to not only create. And deploy your custom template but also provides you with some common templates.
For example, the templates available in te Azure Quickstart Templates repository on GitHub.
Create via Azure Portal
Furthermore, you can also use the Azure Portal to create your ARM Templates. First use the create new resource. Next define the resource we want to be created and then select the Download a template for automation from the Review + Create screen.
This approach is particularly useful when you are new to ARM Templates and are first getting started.
Azure Quickstart Template – GitHub
Finally, the Azure Resource Manager Quickstart Templates repository on GitHub is also a great resource. Because it contains templates that have been created by the community for the community. So there’s a good chance that there is already a template that meets your requirements. And even if the templates in the repository do not completely fulfil your requirements you can use them as a reference. A searchable template index is available here, as well as in Visual Studio Azure Resource Manager Tools.
Test ARM Templates
In this section of we will look at the different ways that you can test your ARM Template, before deploying them. Testing is a critical you create and deploy ARM templates.
Test-AzResourceManagerGroupDeployment cmdlet
First, you should validate the syntax of your templates and check for missing values.
You can use Test-AzResourceManagerGroupDeployment cmdlet from the Az PowerShell Module in order to validate the syntax of your templates. And check for any missing values before you deploy them.
In fact, the Azure Resource Manager uses Test-AzResourceManagerGroupDeployment as its built-in validation. And runs it before deploying your AMR Templates, to prevent deployments from failing halfway through.
The Test-AzResourceManagerGroupDeployment cmdlet only returns messages when it has an error. Therefore, if the template is successfully validated the cmdlet returns nothing. However, you are able to specify the -verbose parameter and see the output of a successful validation.
ARM Template Test Toolkit
Next, you can use the ARM Template Test Toolkit to check your templates against some of the recommended practices. And see if they are compliant.
The ARM Template Test Toolkit has a set of default tests that you can use. For example, checking that there are no hard-code values for secure parameters in your templates. However, these tests are recommendations rather than requirements so you have the flexibility to pick which tests are applicable to your situation and quality goals. In addition to being able to exclude tests that are not relevant the toolkit allows you to create and add your own tests.
What-if Operation
Last but not least you can use the what-if operation and see what changes will be made to your resources when your template is deployed. In other words, the what-if operation does not actually make any changes but rather allows you to see what would change if the template was deployed.
In the same way that ARM templates can be deployed at different scopes, that is tenant, management group, subscription and resource group scopes. So too can the what -if operation be supported at these scopes. In addition you can use the what-if operation with Azure PowerShell, Azure CLI, or REST API operations.
Deploy ARM Templates
There are several different ways to deploy your ARM Templates. Including using the Azure Portal, Azure CLI, Azure PowerShell Module and also the Azure REST API. These options are covered in further details, below.
Azure Portal
You can use the Template deployment (deploy using custom templates) extension from the Azure Marketplace to deploy your ARM Templates from the Azure Portal. The Template deployment (deploy using custom templates) extension has online editor for creating and editing custom templates. As well as providing common templates and templates from the Azure Quickstart Template repository on GitHub.
In order to deploy your ARM Template to the desired resource group. You must first, upload your template and parameters files to the editor. Then, save them and finally deploy them. In addition, you will need to accept the terms and conditions. And in spite of Template deployment being a free extension, you will also need select Purchase to deploy your templates. However your subscription will not be charged.
Learn more about deploying template via the Azure Template deployment extension here.
Azure CLI
You can also use the Azure CLI to deploy your ARM Templates. Including a locally installed version of the CLI or the Cloud Shell available in the Azure Portal.
The scope for your deployment can be set with the following commands:
- Tenant: az deployment tenant create –location –template-file
- Management Group: az deployment mg create –location –template-file
- Subscription: az deployment sub create –location –template-file
- Resource Group: az deployment group create –resource-group –template-file
Moreover, Azure CLI allows you to deploy local files or templates stored in remote locations such as an Azure Storage Account or source control repository like GitHub.
Azure PowerShell
Similarly, you can use the Azure PowerShell module to deploy your ARM Template. And just like the Azure CLI lets us deploy to resources to different scopes so too does the Azure PowerShell module. By using the following commands:
- Tenant: New-AzTenantDeployment -Location -TemplateFile
- Management Group: New-AzManagementGroupDeployment -Location -TemplateFile
- Subscription: New-SubscriptionDeployment -Location -TemplateFile
- Resource Group: New-AzResourceGroupDeployment -ResourceGroupName -TemplateFile
Again, just like Azure CLI the Azure PowerShell module also allows you to deploy local files or templates stored in remote locations such as an Azure Storage Account or source control repository like GitHub.
Azure REST API
Last but not least, you can also use the ARM REST API to deploy your ARM Templates.
In the same way that the Azure CLI and Azure PowerShell module allows you to deploy your ARM Templates to different scopes. The Azure REST API also allows you to deploy your ARM Templates to different scopes by calling the appropriate endpoint. For example,
Tenant
PUT
https://management.azure.com/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-10-01
Management Group
PUT
https://management.azure.com/providers/Microsoft.Management/managementGroups/{groupId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-10-01
Subscription
PUT
https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-10-01
Resource Group
PUT https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.Resources/deployments/{deploymentName}?api-version=2019-10-01
Troubleshooting ARM Template deployments
Importantly, there are two types of errors that you can receive when deploying ARM Templates. The first being a validation error and the second being a deployment error.
Validation Errors
Validation errors happen when your template fails the built-in validation that takes place before the deployment begins.
Generally, by syntax errors or missing values in the template are the cause of these type of errors. Including situations where deploying the resources in the template would exceed a subscription quota.
Because validation errors happen before deployment has taken place they are only recorded in the Azure Activity Log and not Deployment History.
Deployment Errors
In contrast to validation errors, deployment errors are any failed conditions that occur during a deployment. For this reason both the Azure Activity Log and the Deployment History contain a log of these errors.
Therefore you can retrieve both the deployment failure codes and messages with the Azure PowerShell module and the Azure CLI.
Azure PowerShell
(Get-AzResourceGroupDeploymentOperation -DeploymentName <deployment-name> -ResourceGroupName <resource-group-name>).Properties.statusMessage
Azure CLI
az deployment operation group list –name <deployment-name> -g <resource-group-name> –query”[*].properties.statusMessage
Debug logging
Subsequently, you can also enable debug logging when deploying your ARM Template. Thus more information about the deployment will be available.
For example, in Azure PowerShell you can set the DeploymentDebugLogLevel parameter to All, ResponseContent or RequestContent. Whereas the Azure CLI doesn’t support turning on debugging, only retrieving debug logging.
By and large, when troubleshooting a validation or deployment issue it is often best to test parts of your template. For instance, you can create a simplified version and gradually add resources to it. So that you can identify where the issue is coming from.
To conclude
In this article, Create and Deploy ARM Templates you have learned the basics of how to create, test, deploy and troubleshoot ARM templates. Including,
- What authoring tools you can use to create ARM templates
- The different tools that you can use to test your ARM templates
- Different methods for deploying ARM templates
- How to troubleshoot ARM template deployments
Now that we’ve covered some of the basics of how we can create, test, deploy and troubleshoot our ARM Templates we’re ready to look how we can use Azure DevOps to build CI/CD pipeline for our ARM Templates
Thank you for reading. We hope that this article has help you in getting started with ARM templates.
Keith Jenneke
Managing Director | DevOps & Cloud Lead