ARM Templates are meant for automating deployments, for better understanding of the ARM concepts consult this document. I’m writing this under the assumption that you are interested in writing your own ARM templates and got lost at some point.
Obviously consult ARM syntax. And general ARM guidelines. But this shouldn’t be your case. But this document might help you, design patterns for Azure Resource Manager templates when deploying complex solutions.
Basics. Where do I start?
Well, if you are not interested in inventing the wheel again, I’d recommend starting by finding some relevant examples on the web.
There are 3 main sources of ARM Templates:
- Github ARM examples repository
- Search engine (thou, seldom this does work)
- Your own collection of templates (well…)
Once you’ve found something that looks like what you need (or almost looks like that) you can start working on it. If not, try other ways of making your life easier:
- “Automation Script” button on the Azure Portal
- Look through already deployed templates and export them
- Azure Explorer
- Azure Automation option
All of these are doing exactly the same, they are giving you a way to export existing resources you have in Azure into ARM Template. So obviously you should have those resources in Azure before you export them, but that is pretty easy to do.
But bear in mind, all of these ways are nowhere near perfect, they cannot export certain things\properties\parameters, so after you’ve exported a template, read through it (or try deploying) and figure out if something is missing from the template.
Working with Azure Explorer is pretty intuitive, so I won’t explain it. It could help you out if you are looking for some specific property that didn’t get exported with “Automation Script”, also looking at already deployed templates could work when “Automation Script” doesn’t.
Azure automation option can be used when you are creating resource in Azure using the portal, when you are about to deploy it, you can notice “Automation option” button near the deploy button.
The thing with “Automation option” most of the time it uses a slightly different template to deploy stuff, which can help you.
How do I fix missing properties? ARM Schemas!
ARM Templates have a JSON schema, and that schema is well defined, I’ve linked the schema definitions repository. You can work your way through the schema to create a Template from scratch, but I doubt any sane person could handle all the humiliation they would have to go through to do that. Luckily, there are ways to ease the pain:
- Visual Studio code with Azure Resource Manager Tools and ARM Snippets
- Visual Studio with Azure SDK
Also some usefull hotkeys for VS Code: Alt+Shift+F – format the JSON template, so it looks pretty and easier to read, Ctrl+Shift+M – find errors and show them. If you select the language of the file as JSON, VS Code will offer intellisense when working with ARM Templates (if you’ve installed extensions). Pretty sure Visual Studio has the same capabilities, I haven’t really worked with it a lot.
What is convenient with Visual Studio it allows to navigate between resources in the template (similar to what you can do in the portal). This is pretty useful when you are working with a big template.
More information on both: VS Code and Visual Studio.
Sometimes, intellisense doesn’t help, and to fix that you could consult the schema. Say you want to know, what parameters are there for VM OSProfile, you go to the “schema master” and search for the entity you are interested in. Since we want a Virtual Machine property we will look for virtual machine schema under “resources” and there we will find reference schema (“http://schema.management.azure.com/schemas/2015-08-01/Microsoft.Compute.json#/resourceDefinitions/virtualMachines”). You download that schema and look through it to find relevant information, this time its OSProfile (this is where Alt+Shift+F hotkey comes in handy, as those definitions are minimized, so not readable):
As you probably noticed, some of those are links to another objects in the schema, they could easily be located with a quicl Ctrl+F, unless they link to another schema file, in that case, look in that file.
This section above is left only for historical purposes, right now your best bet is to use new Azure Template documentation. It offers a more convenient way to achieve the same result you would with ARM Schemas and much faster.
As you can see, this is an example of a Key Vault resource Schema, but as you can see this example doesn’t offer a way to create a Key Vault secret, which basically makes this pretty useless. Why would you need a Key Vault without any entities stored in it? Why would you need to use Powershell or something else to create secrets? Well, it turns out you don’t need to do that, you can do that with an ARM Template, here’s an example:
Let’s take that one step further, We know that “anything” is possible using Azure REST API. But what if we want to create a secret that is disabled (not that there is a reason for that, but We are just using that as an example) or not usable after certain date. Looking at the REST Api reference for creating a Key Vault secret We can notice that there are properties to do that.
Well, lets try adding that to the template:
If you test it you will see something like this:
In other words, it worked. Well, that gives us an idea on how to extend ARM Templates despite the fact that neither ARM Schema, nor official ARM Templates documentation list those fields\properties as possible.
TLDR \\ Short Summary
I recommend using this “workflow” when working with ARM Templates:
- Look for existing examples on the web
- Export existing resources to create a base template (if you cant find an example, or if you are missing a lot of properties)
- Consult the schema and intellisense when working your way through the template, use appropriate free tools, don’t make your life harder
- Try deploying your template and see what the errors are and fix them, errors can be obtained in the portal or using powershell\cli (and probably all the sdk’s)
- Always check for known errors
- Enable debug mode
- Sometimes ARM engine will throw something like: “Error at line 1, column 2356”, easiest way to handle such an error – minify your JSON and look for character 2356 in the result.
- Use official MS guidance to troubleshoot ARM deployments
There exists an ArmWiz (and an old version) fancy thing which might help someone someday, I do not see much value in it, as it has got no intellisense, doesn’t create meaningful resources when you add them, but it can help you make sense of an existing big template. Reference.
I have to take my words back on this one, this is pretty useful if you are just starting to work with a big template that you didn’t put together. So it can be really useful.
I’ve heard several times that you cannot use reference to other resource in the template outside of the output section. This is false. You can do that, the only requirement is that the resource should be deployed after the resource it is referencing, which is quite logical.