Azure Resource Manager Templates 101

April 5, 2017 By Introductions One Comment

Azure has moved towards the resource manager (ARM) model for all new versions. Both the new portal and AzureRM PowerShell use ARM. The templates are based on JSON (Javascript Object Notation) and allow for incremental and idempotent deployments, so when an error occurs, you can fix and re-deploy without affecting existing resources.

Using a simple JSON file you deploy any number of resources into a resource group. The simplest version of such a file is the following. Note that Microsoft Docs actually leaves out the contentVersion parameters which is required.

There are five properties you can edit. Required are contentVersion , resources  and $schema .

Use the contentVersion parameter to distinguish different versions of the template. Parameters contains questions the user has to answer when deploying the file. Variables are re-usable JSON fragments.

The resources property contains the collection of resources you want to deploy.

It is possible to execute a hierarchy of template files. In this case you can use the outputs property to pass data back to a parent file.

Deploying the file

ARM template are deployed into a resource group. You may want to create one for test purposes which you can delete afterwards.

Deleting a resource group will deleted all resources it contains. Not only the ones you deploy via the script.

Next you can validate the template file.

Then deploy the file to the specific Azure resource group.

Instead of -TemplateFile  you can also use -TemplateUri  and provide a URI to the file.

Visualizing the file

Microsoft is developing an online editor and visualizer for ARM templates at armviz.io. It’s still in its infancy at the time of writing.

Checking the deployment status

Depending on the size of your file the deployment may take a while to complete. For any deployment you can check the status for the resource group.

Declaring parameters

Templates may contain parameters. You can deploy a parameters file when deploying. The user must enter any missing parameters. Or if you execute without a parameters file, all parameters.

The basic format of parameters is as follows.

The name specifies what to reference from other parts of the template. The available types are:

  • string (i.e. “alice”),
  • int (a number 42),
  • bool (i.e. true or false),
  • object (a JSON notation, i.e. { firstName: “alice”, lastName: “doe” }) or
  • array (a JavaScript array, i.e. [1,2,3] or [“a”,”b”,”c”]).

Anyone with access can to your subscription can read these properties in the logs, the portal and other places. To hide these values (e.g. for passwords) you can use two secure variants. The deployment mechanism uses the values and then discards them. See our future post on using parameters in resource templates.

Declaring variables

Variables can be simple strings or JSON fragments.

Using variables, parameters and formulas

The deployment engine interprets values in square brackets. These can contain a set of formulas. One of the simplest is using a variable value.

Or using parameters:

But there are many more including functions you can use to manipulate the values. For a reference see Microsoft Docs’ template functions.

This applies to properties in resource definitions, variables and parameters. But it does not work in parameter files. The following example uses the special resourceGroup()  method which returns a JSON object.

Creating resources

In the resources section you define the resources. Each resource definition depends on the resource type you’re targetting. The required properties are:

But each resource requires further properties. Microsoft Docs is the best reference for the schema definition of ARM resources. Click on the Schema definition for the resource you want to add. For example the storage schema gives you a starting point to adapt to your needs:

There are other useful properties that are available for all resource types.

Specify a JSON object as property “tags” or a “comments” string for easier management.

You specify relationships and dependencies on one of two ways. You can define a property “dependsOn”. There you provide a list of comma-seperated resource names. The second approach is to add child resources under the property “resources”. This way you define the hierarchy. Resources are created from top to bottom

Microsoft provides a GitHub repository of example resource templates.

Tip: The free Visual Studio Code gives you IntelliSense (inline help) for writing templates.

Editing with Visual Studio

After installing the Azure SDK.NET you can create a “Azure Resource Group” project in Visual Studio. This gives you the JSON Outline editor with a wizard for adding most resource types. The wizard asks for some properties, but you will still have to edit the JSON to complete the file.

Naming Resources

Microsoft has a recommendation for naming resources in Azure. I use a simpler approach and believe naming should progress with your needs.

Many resources in Azure require globally unique names (often they represent subdomains). A short (3-4 letters) prefix for the organisation you represent is my starting point.

Next you will want to distinguish between production and other resources. Even if you split your Azure resources into productive and other subscriptions. The name must be globally unique.

Then append the resource type to the name to simplify listings.

This could be sufficient for some organisations that host one system. But sooner or later you may end up hosting multiple systems. So add a short (3-4 letters) system name where applicable.

Some resources (e.g. AppService plans) are shared between systems. In this case numbering is appropriate.

There are couple of special instances you will encounter. For example some resources do not allow dashes. In these cases you can convert the names to camel-casing. This casing should be preserved in table listings. But it should be irrelevant for addressing the resource.

As you grow and create international resources you will want to add a data center suffix.