Edit

Tutorial: Add template functions to your ARM template

  • Article

In this tutorial, you learn how to add template functions to your Azure Resource Manager template (ARM template). You use functions to dynamically construct values. In addition to these system-provided template functions, you can also create user-defined functions. This tutorial takes 7 minutes to complete.

Prerequisites

We recommend that you complete the tutorial about parameters, but it's not required.

You need to have Visual Studio Code installed and working with the Azure Resource Manager Tools extension, and either Azure PowerShell or Azure CLI. For more information, see template tools.

Review template

At the end of the previous tutorial, your template had the following JSON file:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageName": {
      "type": "string",
      "minLength": 3,
      "maxLength": 24
    },
    "storageSKU": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_RAGRS",
        "Standard_ZRS",
        "Premium_LRS",
        "Premium_ZRS",
        "Standard_GZRS",
        "Standard_RAGZRS"
      ]
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-09-01",
      "name": "[parameters('storageName')]",
      "location": "eastus",
      "sku": {
        "name": "[parameters('storageSKU')]"
      },
      "kind": "StorageV2",
      "properties": {
        "supportsHttpsTrafficOnly": true
      }
    }
  ]
}

Suppose you hard-coded the location of the Azure storage account to eastus, but you need to deploy it to another region. You need to add a parameter to add flexibility to your template and allow it to have a different location.

Use function

If you completed the parameters tutorial, you used a function. When you added "[parameters('storageName')]", you used the parameters function. The brackets indicate that the syntax inside the brackets is a template expression. Resource Manager resolves the syntax instead of treating it as a literal value.

Functions add flexibility to your template by dynamically getting values during deployment. In this tutorial, you use a function to get the resource group deployment location.

The following example highlights the changes to add a parameter called location. The parameter default value calls the resourceGroup function. This function returns an object with information about the deployed resource group. One of the object properties is a location property. When you use the default value, the storage account and the resource group have the same location. The resources inside a group have different locations.

Copy the whole file and replace your template with its contents.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageName": {
      "type": "string",
      "minLength": 3,
      "maxLength": 24
    },
    "storageSKU": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_RAGRS",
        "Standard_ZRS",
        "Premium_LRS",
        "Premium_ZRS",
        "Standard_GZRS",
        "Standard_RAGZRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-09-01",
      "name": "[parameters('storageName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageSKU')]"
      },
      "kind": "StorageV2",
      "properties": {
        "supportsHttpsTrafficOnly": true
      }
    }
  ]
}

Deploy template

In the previous tutorials, you created a storage account in the East US, but your resource group is created in the Central US. For this tutorial, you create a storage account in the same region as the resource group. Use the default value for location, so you don't need to provide that parameter value. You need to provide a new name for the storage account because you're creating a storage account in a different location. Use store2, for example, as the prefix instead of store1.

If you haven't created the resource group, see Create resource group. The example assumes you've set the templateFile variable to the path to the template file, as shown in the first tutorial.

New-AzResourceGroupDeployment `
  -Name addlocationparameter `
  -ResourceGroupName myResourceGroup `
  -TemplateFile $templateFile `
  -storageName "{new-unique-name}"

Note

If the deployment fails, use the verbose switch to get information about the resources being created. Use the debug switch to get more information for debugging.

Verify deployment

You can verify the deployment by exploring the resource group from the Azure portal.

  1. Sign in to the Azure portal.
  2. From the left menu, select Resource groups.
  3. Check the box to the left of myResourceGroup and select myResourceGroup.
  4. Select the resource group you created. The default name is myResourceGroup.
  5. Notice your deployed storage account and your resource group have the same location.

Clean up resources

If you're moving on to the next tutorial, you don't need to delete the resource group.

If you're stopping now, you might want to delete the resource group.

  1. From the Azure portal, select Resource groups from the left menu.
  2. Type the resource group name in the Filter for any field... text field.
  3. Check the box next to myResourceGroup and select myResourceGroup or your resource group name.
  4. Select Delete resource group from the top menu.

Next steps

In this tutorial, you use a function to define the default value for a parameter. In this tutorial series, you continue to use functions. By the end of the series, you add functions to every template section.

Add variables