How to Get your ARM Template
Of course, you could build your ARM template from scratch. However, there many quickstart templates available on GitHubd. Even more, you could also get Azure to generate the template for you!
If your building a new solution, go in the Azure portal (portal.azure.com) and start creating your resource as usual. But stop just before clicking on the Create button. Instead click on the link on his side named Download template and parameters. That will open a new blade where you will be able to download the template, parameters files, and a few scripts in different languages to deploy it.
If your solution is already deployed, you still have a way to get the template. Again, from the Azure portal, go to the resource group of your solution. In the left option panel, click on Automation script.
Step 1 - Use Git
Once you have your ARM template and a parameter file, move them in a folder and initialize a Git Repository. Even if it's only a local one this will give you an infinite of Ctrl-Z. Doing multiple commit along your journey to get a better and cleaner template, you will always have options to get back when your template was "functional".
A fantastic tool to edit ARM template is Visual Studio Code. It's free, it supports natively Git, and you can install great extensions to help you.
Step 2 - Validate, Validate, Validate, then Commit
az group deployment validate --resource-group cloud5mins --template-file .\template.json --parameters .\parameters.json
Step 3 - Reduce the Number of Parameters
Nobody like tons of questions. Too many parameters is exactly like too many questions. So reduce them to the maximum. We cannot just delete those unwanted parameters, but they are still providing important information. Instead move them in the
variables section.You can do that in different ways, let me share mine. I start with the parameter files and bubble-up any parameter that I would like to keep. Next Cut/Paste all the unwanted parameters to a new file. Then I use the multi-cursor selection of VSCode to clean them in 2 clicks.
Once we have all parameters "converted" in variables, copy them into the
variables section of the ARM template. You will need to delete the parameter equivalent from the top of the template.Now that we have a clean list of parameters, and variables, we must fix the references to the converted parameters. To do that replace all
parameters() references by variables().For exemple this:
parameters('networkInterfaceName')
will become that:
variables('networkInterfaceName')
Now that we have a more respectable list of parameters, we must be sure that what we expect from them is clear. To do that we have two simple feature at our disposal. The first one of course the name. Use a complete and clear name. Resist the temptation to shorten everything or use too many acronyms. The second is to use metadata description. This information will be displayed to users through the portal as tooltips.
"adminUsername": {
"type": "string",
"metadata": {
"description": "Name of Administrator user on the VM"
}
}
Step 4 - Use Use Unique String
When you deploy in Azure some names are global, and by definition need to be unique. This is why adding a suffix or a unique identifier to your named is a good practice. An excellent way to get an identifier is to use the function
uniqueString(). This function will create a 64Bits hash based on the information passed in parameter."suffix": "[uniqueString(resourceGroup().id, resourceGroup().location)]"
In the example just above, we pass the identifier of the resource group and its name. It means that every time you will be deploying in the same resource group and at that location
suffix will be the same. However, if your solution is deployed in multiple locations (for a disaster recovery, or another scenario), suffix will have a different value.To use it, let's say the name of a virtual machine was passed as a parameter. Then we will create a variable and concatenate the parameter and our suffix.
"VMName": "[toLower(concat(parameters('virtualMachineName'), variables('suffix')))]",
Then instead of using the parameter inside your ARM template, you will be using this new variable.
Step 5 - Use Variables
One of the great strengths of using ARM template is that we can use them over and over. This is why we want to avoid anything that his static name or value. When we generated template from the Azure portal, these templates are a snapshot of that particular instances. The best way to stay structured and avoid too fixed names is to leverage variables.
When you use an ARM template generated from a "live" and already deployed solution the ARM will contains a lot of very specific information about this instance (Comments, ResourceIDs, States, etc.). When you are building a generic template don't hesitate to delete those.Let's see some examples.
"RGName": "[toLower(resourceGroup().name)]",
"VMName": "[toLower(concat(parameters('virtualMachineName'), variables('suffix')))]",
"virtualNetworkName": "[concat(variables('RGName'), '-vnet')]",
"networkInterfaceName": "[toLower(concat(variables('VMName'),'-nic-', variables('suffix')))]",
"networkSecurityGroupName": "[toLower(concat(variables('VMName'),'-nsg-', variables('suffix')))]",
"diagnosticsStorageAccountName": "[substring(concat(variables('RGName'), 'diag', variables('suffix')), 0, 24)]",
You may wonder why we need the first variable
RGName , since the resource group name is already available through the resourceGroup() function? Some resources, like Azure Blob Storage's name, must only contain lowercase characters. By making a variable we avoid repeating the to toLower() every time.You can concatenate two, or more variables and/or string with the "very popular" function
concat(). Sometimes, the name built by all those string is too long. You can trim it by using the function substring(stringToParse, startIndex, length). In this case, the Azure Blob Storage required a name with a maximum of 24 characters.To learn more about all the available function and how to use it visit the Azure Resource Manager template functions page from the Microsoft documentation.
Step 6 - Create "T-Shirt Size" or smart options
The best way to build a good template is to think like the people who will use it. Therefore, a developer may not know what the difference between a Standard_D2s_v3, a Standard_F8 or a Standard_H8. But will clearly know if he needs a medium, a large, or a web development VM.
That means that we will create a parameter with only specific values allowed, and base on that simple selection we will take more specific and technical decision. See the declaration of the following parameter.
"EnvironmentSize": {
"type": "string",
"defaultValue": "medium",
"allowedValues": [
"medium",
"large"
],
"metadata": {
"description": "Medium for regular development. Large for huge memory usage"
}
}
This parameter will only allowed two string "medium" or "large", anything else will return a validation error. If nothing is passed the default value will be "medium". And finally using a metadata description to make sure the purpose of the parameter is clear and well defined.
Then you define your variable (ex: TS-Size) as an object with two properties, or as many as you have allowed values. For each of these properties, you could have many other properties.
"TS-Size":{
"medium":{
"VMSize": "Standard_D2s_v3",
"maxScale": 1
},
"large":{
"VMSize": "Standard_D8s_v3",
"maxScale": 2
}
}
Then to use it, we just need to chained the variables and parameter. Notice how we have nested square brackets... This will use the TS-Size.medium.VMSize value by default.
"vmSize": "[variables('TS-Size')[parameters('EnvironmentSize')].VMSize]"
I hope you will find those tips as useful, as I found they are. If you have other suggestions or recommendations, don't hesitate to add them in the comment section or reach me out.
The full ARM template is available at : https://gist.github.com/FBoucher/adea0acd95f86e5838cf812c010564cf
In Video Please!
If you prefer, I also have a video version of that post.