Creating your first Azure Resource Manager (ARM) template

If you’re manually creating infrastructure for your next app in Azure, you should consider using an Azure Resource Manager (ARM) template.

An ARM template is essentially a JSON file that describes the infrastructure you want to create in the Azure cloud. It can be run as many times as you like to spin up identically-configured environments.

Create the template

The first step when using an ARM template is to create the template file. If you’d rather start with an example template, Microsoft has an entire Github repo with some templates that you can clone.

The base template - normally called azuredeploy.json - is made up of the following structure:

1
2
3
4
5

{
  “$schema”: “https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#”,
  “ContentVersion”: “1.0.0.0”,
  “Resources”: []
}

The elements can be described as follows:

• $schema: Refers to the properties that can be used within the template. If you were to load the URL in your web browser, it would return the elements and a description of each that you can use within your template. When uploading a template, these get validated to ensure you haven’t made any mistakes.
• contentVersion: This is an internal version number for you to use to reference the current template. It should be in the format X.X.X.X, with X being any integer. You should only change this value in your template when a significant change is made.
• resources: This is an array that will contain a description of all the Azure resources that your app or service needs. For now it’s empty.

Add resources to the template

As mentioned above, within the resources section of the template you need to describe the Azure services that you wish to provision. Each Azure service has a set of properties that can be set, with some mandatory. By default, a resource requires:

• type: The type is a string that refers to a namespace of the resource provider and the name of the type of resource that you wish to provision. For example, Microsoft.DocumentDB/DatabaseAccounts implies you want to create a DatabaseAccount from the Microsoft.DocumentDB namespace
• apiVersion: Similar to the template $schema version, each Azure resource type also publishes versions of their schema. This property allows you to specify which schema or version of the resource type you’d like to use and is mandatory
• name: The human-readable string name that you’d like the resource to be called

While not mandatory, a location element is normally provided as well to specify the location where you want the resource to reside (eg. Australia East).

Luckily Microsoft publishes a full list of properties for each resource type. But if you’re still not sure, for most resources you can manually create the resource using the Azure Portal and go to the “Export Template” tab for the resource, and Microsoft will generate a template for you.

For this tutorial, let’s create a simple functions app. Add the following to your resources section in your azuredeploy.json file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

   "resources": [
        {
            "type": "Microsoft.Web/sites",
            "apiVersion": "2018-02-01",
            "name": "[parameters('siteName')]",
            "kind": "functionapp,linux",
            "location": "[parameters('location')]",
            "dependsOn": [
                "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]"
            ],
            "properties": {
                "name": "[parameters('siteName')]",
                "siteConfig": {
                     "appSettings": [
                        {
                            "name": "FUNCTIONS_WORKER_RUNTIME",
                            "value": "python"
                        },
                        {
                            "name": "FUNCTIONS_EXTENSION_VERSION",
                            "value": "~2"
                        }
                    ]
                },
                "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', variables('hostingPlanName'))]",
                "clientAffinityEnabled": false
            }
        },
        {
            "type": "Microsoft.Web/serverfarms",
            "apiVersion": "2018-02-01",
            "name": "[variables('hostingPlanName')]",
            "location": "[parameters('location')]",
            "kind": "linux",
            "properties":{
                "reserved": false
            },
            "sku": {
                "Tier": "Dynamic",
                "Name": "Y1"
            }
        }
    ]

The above creates a Linux App Service hosting plan. It uses the consumption function tier (Y1) and isn’t a reserved plan.

The template also creates a function app (Microsoft.Web/sites) that dependsOn the hosting plan.

If you look closely, you might notice that some elements refer to variables and parameters. Let’s dive deeper into what they are.

What are parameters?

Parameters allow you to specify a value each time you deploy a template. For example, if you had a template and wanted to create a production and staging environment with it, you could create a environment parameter that would allow you to specify staging or production in resource names without modifying the template file each time.

If you didn’t use a parameter, you’d need to change the hard-coded string value in your azuredeploy.json file each time you wanted to change to a new environment.

Similarly if you wanted to be able to deploy your template to a different Azure location quickly, you could specify a location parameter. Then you could deploy to any Azure region by simply providing a new location parameter value - with no change to the template file required.

Within the template file, parameters sit in a top-level parameters element as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  “$schema”: “https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#”,
  “ContentVersion”: “1.0.0.0”,
  “Resources”: [],
  “Parameters”: {
    “hostingPlanName”: {
      “type”: “string”,
      “DefaultValue”: “”,
      “Metadata”: {
           “Description”: “The name to give your hosting plan”
      }
   }
}

Parameters support a number of elements, but the most common include:

• type: The type of value provided (eg. String)
• defaultValue: A default value to use if one isn’t provided when the template is deployed
• metadata.description: A description of what the parameter represents

Parameters can be set when deploying using the Azure CLI or PowerShell. Here’s an example of how you would provide a location parameter using the Azure CLI:

1
2
3
4
5

az group deployment create \
  —-name mytemplatename \
  —-resource-group yourResourceGroup \
  —-templateFile $templateFile \
  —-parameters environment=staging

Referencing the parameter is done using the following syntax - you can see a full example in the template we defined earlier with resources:

1

"location": "[parameters('location')]"

What are variables?

While parameters allow you to specify values when _deployin_g a template, variables allow you to reuse values internally within your template file without duplication. For instance, if you had a value that you use in 3 different resources (such as a location or in the example above the hostingPlanName) that you didn’t want to expose to those running your template you could use a variable.

Like parameters, variables are also top-level elements. They’re simpler to specify, as you don’t need to provide descriptions, types and default values. They look like this:

1
2
3
4
5
6
7
8

{
  “$schema”: “https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#”,
  “ContentVersion”: “1.0.0.0”,
  “Resources”: [],
  “Variables”: {
     “HostingPlanName”: “yourHostingPlanName”
  }
}

You can then reference the variable within your resource definitions using the following syntax as seen in the resources section in the template we created earlier:

1

"name": "[variables('hostingPlanName')]"

Summary

In this post, you’ve learnt about how a template is structured, and what each element means. Stay tuned for our next post on deploying your template.