Understand Syntax of Azure Resource Manager (or ARM) Templates

The infrastructure for an application generally consists of many components. It consists of an application code itself, a server somewhere to run that code (typically a virtual machine), a storage to hold the data, a database and a network. You may also want to have integration with 3rd party services. So in order for your application to work, either you want to have all this in place, or none at all. Same is true whenever you would want to deploy your application in Microsoft Azure. Azure Resource Manager or ARM is a way to manage all interdependent parts as one resource group. You can deploy, update or delete all the resources required for your application to work.

With Azure Resource Manager, you can create a template that defines all the interdependent parts required for your application. This template is defined using JSON format. See more details on ARM templates here and about JSON here. In this blog post, we’ll understand the syntax to create ARM templates.

In its simplest and most basic form, the ARM template is having following syntax:

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "",
    "parameters": {  },
    "variables": {  },
    "resources": [  ],
    "outputs": {  }
}

Let’s understand this syntax first.

$schema: It’s a mandatory element. It specifies the location of the JSON schema file that describes the version of the template language.

contentVersion: This is also a mandatory element. It specifies the version of the template (such as 1.0.0.0). You can provide any value for this element. When deploying resources using the template, this value can be used to make sure that the right template is being used. You can also choose to leave this empty.

parameters: It specifies the values that are provided when deployment is executed to customize resource deployment.

variables: It specifies the values that are used as JSON fragments in the template to simplify template language expressions.

resources: It specifies the resource types that are deployed or updated in a resource group.

outputs: It specifies the values that are returned after deployment.

Each of these element contain properties that can be set.

Parameters

In the parameters section of the template, you can specify which values you can input when deploying the resources. These parameter values enable you to customize the deployment by providing values that are tailored for a particular environment (such as dev, test, and production). You do not have to provide parameters in your template, but without parameters your template would always deploy the same resources with the same names, locations, and properties. Parameters help to avoid this situation by allowing customized values.

You define parameters with the following structure:

"parameters": {
    "" : {
        "type" : "",
        "defaultValue": "",
        "allowedValues": [ "" ],
        "minValue": ,
        "maxValue": ,
        "minLength": ,
        "maxLength": ,
        "metadata": {
            "description": "" 
        }
    }
}

Out of the above possible values, only parameter-name and type are mandatory elements. Other values are optional and may or may not be required depending on the syntax.

parameterName: Name of the parameter. Must be a valid JavaScript identifier.

type: Type of the parameter value.

defaultValue: Default value for the parameter, if no value is provided for the parameter.

allowedValues: Array of allowed values for the parameter to make sure that the right value is provided.

minValue: The minimum value for int type parameters, this value is inclusive.

maxValue: The maximum value for int type parameters, this value is inclusive.

minLength: The minimum length for string, secureString, and array type parameters, this value is inclusive.

maxLength: The maximum length for string, secureString, and array type parameters, this value is inclusive.

description: Description of the parameter that is displayed to users through the portal.

The allowed types and values are:

  • string
  • secureString
  • int
  • bool
  • object
  • secureObject
  • array

To specify a parameter as optional, provide a defaultValue which can also be a empty string. Do note that all passwords, keys, and other secrets should use the secureString type. If you pass sensitive data in a JSON object, use the secureObject type. Template parameters with secureString or secureObject types cannot be read once the resources are deployed.

Also you should not name parameters with the same name as parameters used for deployment operations.

Variables

In the variables section, you construct values that can be used throughout your template. You do not need to define variables, but they often simplify your template by reducing complex expressions.

You define variables with the following structure:

"variables": {
    "": "",
    "": { 
         
    }
}

The following example shows how to define a variable that is constructed from two parameter values:

"variables": {
    "connectionString": "[concat('Name=', parameters('username'), ';Password=', parameters('password'))]"
}

We can form a fairly complex variable by using various expressions and functions.

Resources

In the resources section, you define the resources that are deployed or updated. This section can get complicated because you must understand the types you are deploying to provide the right values.
You define resources with the following structure:

"resources": [
  {
      "condition": "",
      "apiVersion": "",
      "type": "<resource-provider-namespace/resource-type-name>",
      "name": "",
      "location": "",
      "tags": {
          "": "",
          "": ""
      },
      "comments": "",
      "copy": {
          "name": "",
          "count": "",
          "mode": "",
          "batchSize": ""
      },
      "dependsOn": [
          ""
      ],
      "properties": {
          "",
          "copy": [
              {
                  "name": ,
                  "count": ,
                  "input": {}
              }
          ]
      },
      "resources": [
          ""
      ]
  }
]

Here:

condition: Boolean value that indicates whether the resource is deployed.

apiVersion: Version of the REST API to use for creating the resource. This is a required element.

type: Type of the resource. This value is a combination of the namespace of the resource provider and the resource type. This is a required element.

name: Name of the resource. The name must follow URI component restrictions defined in RFC3986. In addition, Azure services that expose the resource name to outside parties validate the name to make sure it is not an attempt to spoof another identity.

location: Supported geo-locations of the provided resource. You can select any of the available locations, but typically it makes sense to pick one that is close to your users. Usually, it also makes sense to place resources that interact with each other in the same region. Most resource types require a location, but some types (such as a role assignment) do not require a location. See Set resource location in Azure Resource Manager templates. This may or may not be a required value depending upon resource type.

tags: Tags that are associated with the resource. See Tag resources in Azure Resource Manager templates.

comments: Your notes for documenting the resources in your template

copy: If more than one instance is needed, the number of resources to create. The default mode is parallel. Specify serial mode when you do not want all or the resources to deploy at the same time.

dependsOn: Resources that must be deployed before this resource is deployed. Resource Manager evaluates the dependencies between resources and deploys them in the correct order. When resources are not dependent on each other, they are deployed in parallel. The value can be a comma-separated list of a resource names or resource unique identifiers. Only list resources that are deployed in this template. Resources that are not defined in this template must already exist. Avoid adding unnecessary dependencies as they can slow your deployment and create circular dependencies.

properties: Resource-specific configuration settings. The values for the properties are the same as the values you provide in the request body for the REST API operation (PUT method) to create the resource. You can also specify a copy array to create multiple instances of a property.

resources: Child resources that depend on the resource being defined. Only provide resource types that are permitted by the schema of the parent resource. The fully qualified type of the child resource includes the parent resource type, such as Microsoft.Web/sites/extensions. Dependency on the parent resource is not implied. You must explicitly define that dependency.

The resources section contains an array of the resources to deploy. Within each resource, you can also define an array of child resources. Therefore, your resources section could have a structure like:

"resources": [
  {
      "name": "resourceA",
  },
  {
      "name": "resourceB",
      "resources": [
        {
            "name": "firstChildResourceB",
        },
        {   
            "name": "secondChildResourceB",
        }
      ]
  },
  {
      "name": "resourceC",
  }
]

Outputs

In the Outputs section, you specify values that are returned from deployment. For example, you could return the URI to access a deployed resource.

The following example shows the structure of an output definition:

"outputs": {
    "" : {
        "type" : "",
        "value": ""
    }
}

Here:

outputName: Name of the output value. Must be a valid JavaScript identifier.

type: Type of the output value. Output values support the same types as template input parameters.

value: Template language expression that is evaluated and returned as output value.

All of above 3 are required elements. The following example shows a value that is returned in a output section:

"outputs": {
    "siteUri" : {
        "type" : "string",
        "value": "[concat('http://',reference(resourceId('Microsoft.Web/sites', parameters('siteName'))).hostNames[0])]"
    }
}

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s