If all the tests return \u2018success\u2019 then the template is, by definition, valid.<\/p>\n
Basic testing<\/h3>\n
Apart from the functional testing, it is possible to validate whether a template is actually deployable to the resource group you want to deploy. If you use the PowerShell function \u201cTest-AzureRmResourceGroupDeployment\u201d, it will take your template, parse it and check that it is syntactically correct as well as validating that you meet requirements such as not hitting quote limits before you deploy.<\/p>\n
This is really useful, because the ARM template is not compiled. This prevents you from using a \u201cbuild\u201d step in the build process that you could otherwise use to make sure that the ARM template is even deployable. Furthermore, it wouldn\u2019t be ideal in the \u201ccomplete\u201d type of deployments if you deleted various resources and then failed to create all the new resources that you wanted because you had hit your quota limits in Azure.<\/p>\n
ARM template execution<\/h2>\n
There are two important concepts to understand when using ARM templates. The first is that the ARM REST API is the part that actually does the \u201cheavy lifting\u201d. It is this that provides the idempotency of the whole process. The REST API is well documented, updated regularly and available on either the Microsoft docs site or on github if you felt like contributing:<\/p>\n
Azure REST API Reference – https:\/\/docs.microsoft.com\/en-us\/rest\/api\/<\/a><\/p>\n Azure\/azure-rest-api-specs – https:\/\/github.com\/Azure\/azure-rest-api-specs<\/a><\/p>\n There is one set of REST APIs called \u201cResource Management\u201d which is where you send an ARM template. The REST API takes the template and:<\/p>\n If we look at this simple example of an ARM template which will deploy a single storage account:<\/p>\n The process that the REST API goes through is to read the parameter \u201cstorageAccountType<\/strong>\u201d from the parameters that are also passed in at the same time as the deployment. Because the \u201cstorageAccountType<\/strong>\u201d parameter also specifies what the \u201callowedValues<\/strong>\u201d are the parameter is validated against the list of allowedValues<\/strong>. If the parameter passed in has a typo or other mistake then the deployment is cancelled at this point. If you omit the \u201callowedValues<\/strong>\u201d then this check will not happen.<\/p>\n The REST API then creates the variable diagStorageAccountName<\/strong> and the value of the variable is the result of the ARM template functions concat<\/strong> which concatenates the string \u2018diags\u2019 with the output of uniqueString(resourcegroup().id<\/strong>) which will create a unique string for that resource group. The function uniqueString<\/strong> is passed the id of the resource group to use as a base string for uniqueString<\/strong> so it will be unique per resource group. If you need a second string to be unique you would need to pass another string to hash or omit the base string. The function uniqueString<\/strong> is best used with a base string so subsequent deployments do not create new objects each time.<\/p>\n The REST API then uses the resources section to call the resource specific APIs. There is only one resource to create in this example and it is of type \u201cMicrosoft.Storage\/storageAccounts\u201d. The type in the ARM template maps directly to another of the REST APIs<\/em> types which are documented:<\/p>\n The apiVersion<\/strong> tells the resource manager which version of the API to call, the properties you can set and also the behaviour of the API can and does change between versions so it is important you get the correct API version. The API version is specified for each resource so you can deploy two things of the same type (storage account for example) but deploy them using different versions of the REST API.<\/p>\n The location is determined from the function resourceGroup<\/strong>() which returns a list of properties, one of which is location.<\/p>\n The value that is set for \u201csku<\/strong>\u201d is resolved from the parameter \u201cstorageAccountName<\/strong>\u201d. Any value in the JSON template that is surrounded by [ and ] is evaluated as code. The full list of template functions that can be used is documented https:\/\/docs.microsoft.com\/en-us\/azure\/azure-resource-manager\/resource-group-template-functions<\/a><\/p>\n The resource manager then creates the JSON which is going to be sent to the storageAccount<\/strong> REST API which will look like:<\/p>\n This JSON is then sent to the following URI as a PUT request:<\/p>\n \/subscriptions\/{subscriptionId}\/resourceGroups\/{resourceGroupName}\/Microsoft.Storage\/storageAccounts\/diags{someUniqueStringCreatedAtRuntime}?api-version=2016-01-01<\/p>\n The storageAccounts<\/strong> REST API is then responsible for checking whether there is a storage account with the name we have. If there is not then it creates a new one and makes sure it has the same properties as the ones we pass in. If it already exists then the storage REST API will just ensure the properties are set correctly.<\/p>\n When the storageAccount<\/strong> PUT request happens, if there is something it cannot do such as create an account with the same name as an existing one in another resource group or subscription (maybe even created a different person or organisation) then it will fail. There are also some changes that it finds impossible such as the compute API changing the base image a virtual machine was created for. You will sometimes need to delete resources and start again for some changes.<\/p>\n When the PUT request finishes, the API returns a JSON document which contains the definition of the object that it just created so some things that can\u2019t be known at build time are available. This is useful for cases where you create something like a storage account which creates the access keys when it is created. You could, in your ARM template, reference the key and use that in other objects that need a storage account name and key.<\/p>\n The properties are returned whether or not the object already existed, so in that way you know that whether it is the first time that the resource was created, or the hundredth time it was checked and already existed, you can still deploy downstream dependent resources.<\/p>\n In some cases, you need to deploy resources in a specific order: For instance, in order to create a virtual machine, you will need to deploy a NIC and for a NIC you might want to deploy a public ip address. If you try to create the NIC and reference a public ip address that doesn\u2019t exist, then the deployment will fail. The answer to this is that dependencies, as well as each resource, can have a \u201cdependsOn<\/strong>\u201d section that lists all the dependencies that need to be created before the resource can be created. Dependencies are really useful, but should be used with caution because they limit the number of simultaneous things the resource manager can do. The more dependencies you have and the longer the dependency chains, then the longer that deployments will take.<\/p>\n It is also possible to define dependencies by nesting resources, and in that case child dependencies are created after the parent resource is created.<\/p>\n Finally there is a third way to create a dependency which is to use the \u201creferenc<\/strong>e\u201d template function. What this does is to get the properties of another resource, the same as in the output to the PUT request above. This enables you to do things such as to use an account key from a storage account which may not be known at build time. If you use a reference to access another resource in the template then an implicit dependency is created for you.<\/p>\n The dependencies are documented by Microsoft:<\/p>\n https:\/\/docs.microsoft.com\/en-us\/azure\/azure-resource-manager\/resource-group-define-dependencies<\/p>\n When we deploy resources, we may want just one, but more likely we will want a number of similar resources such as virtual machines to be created. To help with this, there is the \u201ccopy\u201d section which specified how many copies of a resource we want. This is great, because it means that, if we want 100 virtual machines, we don\u2019t have to define 100 resources in the ARM template. The way it works is that you add a copy block to your resource such as:<\/p>\n What this says is that we should have 3 storage accounts created. There are two things to note here: the first is that, because we are saying \u2018make 3 copies of this\u2019, we need to make the name unique amongst the three objects. We do this so that, instead of just using the account name variable, we append the copyIndex<\/strong> which is the id of the copy operation. We do this because, if we pass 1 into the copyIndex<\/strong> function, it starts at 1 rather than 0 so we get accountName1<\/strong>, accountName2<\/strong> and accountName3<\/strong>.<\/p>\n The second thing is that the copy block has a name. This is really useful because we can use it in a dependsOn<\/strong> block and the dependent resources will not be created until all three of the storage accounts have been created. This is useful in such cases as creating virtual machines where you could get the first machine taking longer to deploy than the last. If you didn\u2019t have the ability to reference by copy name you would need to add a dependsOn<\/strong> to all the resources individually which would get messy quickly.<\/p>\n Conditionals are a recent addition to ARM templates. They specify whether or not to deploy a specific resource. This can be useful when handling different environments where, in development, you might only want one virtual machine without a load balancer but in production you might want five machines with a load balancer. To use the same template you could pass the number in as a parameter but to choose whether or not to deploy the load balancer you can return false<\/strong> in the condition<\/strong> property.<\/p>\n In this example we have a \u201ccondition<\/strong>\u201d property that checks whether a parameter is set to \u201cyes\u201d or not.<\/p>\n Conditionals should definitely be used with caution and I would suggest having at least one environment before production where the entire template is deployed. To be fair, they fulfil a need that was missing and which previously involved passing whole blobs of JSON in as parameters.<\/p>\n There are a couple of approaches, the easiest of which is to use the quick start templates created by Microsoft which give examples of how to use most resources. The quick start templates are available here:<\/p>\n https:\/\/azure.microsoft.com\/en-gb\/resources\/templates\/<\/a><\/p>\n The second approach is to deploy some resources: In the azure portal, there is a button called \u201cAutomation Script\u201d which will generate the ARM template to deploy the entire resource group. This always creates a script for the entire resource group even if you click the \u201cAutomation Script\u201d on one particular resource.<\/p>\n Not every type of resource can be generated today, although it seems as if Microsoft keep increasing the scope of the resources that they generate ARM templates for. It might be that you just need to wait a few weeks.<\/p>\n The automation script doesn\u2019t, in my opinion, generate the ideal templates. The names are odd and even though they put names behind parameters they use the name of the resource in the parameter names so it is hard to read and edit the scripts. I would say that they are best used to show how a resource is configured and just take the parts from the script that you need to re-use and manually create the other parts of the template or use a company-shared template to create the ARM template.<\/p>\n The automation also generates the scripts that can be used by different clients such as PowerShell, Bash and C#. This gives you the code you need to send your ARM template to the ARM REST API for processing. Again, these are quite verbose and you don\u2019t need everything. For example, if you are using PowerShell, then all you really need to do is to create the resource group itself if it doesn\u2019t exist, and then call \u201cNew-AzureRmResourceGroupDeployment<\/strong>\u201d from the AzureRM<\/strong> module.<\/p>\n The ARM templates capabilities themselves as opposed to the actual resources are documented:<\/p>\n https:\/\/docs.microsoft.com\/en-us\/azure\/azure-resource-manager\/<\/a><\/p>\n The resources and their properties are documented:<\/p>\n\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2017\/08\/word-image-97.png\")
<\/p>\n\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2017\/08\/word-image-98.png\")
<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2017\/08\/word-image-99.png\")
<\/p>\nWhat else can we do in ARM templates?<\/h2>\n
Defining dependencies<\/h3>\n
Copy Sections<\/h3>\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2017\/08\/word-image-100.png\")
<\/p>\nConditionals<\/h3>\n
![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2017\/08\/word-image-101.png\")
<\/p>\nHow do you get started?<\/h2>\n
Documentation<\/h2>\n