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.
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.
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 degub 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.