Tutorial: Use parameter files to deploy your ARM template

In this tutorial, you learn how to use parameter files to store the values you pass in during deployment. In the previous tutorials, you used inline parameters with your deployment command. This approach worked for testing your Azure Resource Manager template (ARM template), but when automating deployments it can be easier to pass a set of values for your environment. Parameter files make it easier to package parameter values for a specific environment. In this tutorial, you'll create parameter files for development and production environments. It takes about 12 minutes to complete.

Prerequisites

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

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

Review template

Your template has many parameters you can provide during deployment. At the end of the previous tutorial, your template looked like:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "type": "string",
      "minLength": 3,
      "maxLength": 11
    },
    "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]"
    },
    "appServicePlanName": {
      "type": "string",
      "defaultValue": "exampleplan"
    },
    "webAppName": {
      "type": "string",
      "metadata": {
        "description": "Base name of the resource such as web app name and app service plan "
      },
      "minLength": 2
    },
    "linuxFxVersion": {
      "type": "string",
      "defaultValue": "php|7.0",
      "metadata": {
        "description": "The Runtime stack of current web app"
      }
    },
    "resourceTags": {
      "type": "object",
      "defaultValue": {
        "Environment": "Dev",
        "Project": "Tutorial"
      }
    }
  },
  "variables": {
    "uniqueStorageName": "[concat(parameters('storagePrefix'), uniqueString(resourceGroup().id))]",
    "webAppPortalName": "[concat(parameters('webAppName'), uniqueString(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('uniqueStorageName')]",
      "location": "[parameters('location')]",
      "tags": "[parameters('resourceTags')]",
      "sku": {
        "name": "[parameters('storageSKU')]"
      },
      "kind": "StorageV2",
      "properties": {
        "supportsHttpsTrafficOnly": true
      }
    },
    {
      "type": "Microsoft.Web/serverfarms",
      "apiVersion": "2020-12-01",
      "name": "[parameters('appServicePlanName')]",
      "location": "[parameters('location')]",
      "tags": "[parameters('resourceTags')]",
      "sku": {
        "name": "B1",
        "tier": "Basic",
        "size": "B1",
        "family": "B",
        "capacity": 1
      },
      "kind": "linux",
      "properties": {
        "perSiteScaling": false,
        "reserved": true,
        "targetWorkerCount": 0,
        "targetWorkerSizeId": 0
      }
    },
    {
      "type": "Microsoft.Web/sites",
      "apiVersion": "2020-12-01",
      "name": "[variables('webAppPortalName')]",
      "location": "[parameters('location')]",
      "dependsOn": [
        "[parameters('appServicePlanName')]"
      ],
      "tags": "[parameters('resourceTags')]",
      "kind": "app",
      "properties": {
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "siteConfig": {
          "linuxFxVersion": "[parameters('linuxFxVersion')]"
        }
      }
    }
  ],
  "outputs": {
    "storageEndpoint": {
      "type": "object",
      "value": "[reference(variables('uniqueStorageName')).primaryEndpoints]"
    }
  }
}

This template works well, but now you want to easily manage the parameters that you pass in for the template.

Add parameter files

Parameter files are JSON files with a structure that is similar to your template. In the file, you provide the parameter values you want to pass in during deployment.

Within the parameter file, you provide values for the parameters in your template. The name of each parameter in your parameter file must match the name of a parameter in your template. The name is case-insensitive but to easily see the matching values we recommend that you match the casing from the template.

You don't have to provide a value for every parameter. If an unspecified parameter has a default value, that value is used during deployment. If a parameter doesn't have a default value and isn't specified in the parameter file, you're prompted to provide a value during deployment.

You can't specify a parameter name in your parameter file that doesn't match a parameter name in the template. You get an error when unknown parameters are provided.

In Visual Studio Code, create a new file with following content. Save the file with the name azuredeploy.parameters.dev.json.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "devstore"
    },
    "storageSKU": {
      "value": "Standard_LRS"
    },
    "appServicePlanName": {
      "value": "devplan"
    },
    "webAppName": {
      "value": "devapp"
    },
    "resourceTags": {
      "value": {
        "Environment": "Dev",
        "Project": "Tutorial"
      }
    }
  }
}

This file is your parameter file for the development environment. Notice that it uses Standard_LRS for the storage account, names resources with a dev prefix, and sets the Environment tag to Dev.

Again, create a new file with the following content. Save the file with the name azuredeploy.parameters.prod.json.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "contosodata"
    },
    "storageSKU": {
      "value": "Standard_GRS"
    },
    "appServicePlanName": {
      "value": "contosoplan"
    },
    "webAppName": {
      "value": "contosowebapp"
    },
    "resourceTags": {
      "value": {
        "Environment": "Production",
        "Project": "Tutorial"
      }
    }
  }
}

This file is your parameter file for the production environment. Notice that it uses Standard_GRS for the storage account, names resources with a contoso prefix, and sets the Environment tag to Production. In a real production environment, you would also want to use an app service with a SKU other than free, but we'll continue to use that SKU for this tutorial.

Deploy template

Use either Azure CLI or Azure PowerShell to deploy the template.

As a final test of your template, let's create two new resource groups. One for the dev environment and one for the production environment.

For the template and parameter variables, replace {path-to-the-template-file}, {path-to-azuredeploy.parameters.dev.json}, {path-to-azuredeploy.parameters.prod.json}, and the curly braces {} with your template and parameter file paths.

First, we'll deploy to the dev environment.

$templateFile = "{path-to-the-template-file}"
$parameterFile="{path-to-azuredeploy.parameters.dev.json}"
New-AzResourceGroup `
  -Name myResourceGroupDev `
  -Location "East US"
New-AzResourceGroupDeployment `
  -Name devenvironment `
  -ResourceGroupName myResourceGroupDev `
  -TemplateFile $templateFile `
  -TemplateParameterFile $parameterFile

Now, we'll deploy to the production environment.

$parameterFile="{path-to-azuredeploy.parameters.prod.json}"
New-AzResourceGroup `
  -Name myResourceGroupProd `
  -Location "West US"
New-AzResourceGroupDeployment `
  -Name prodenvironment `
  -ResourceGroupName myResourceGroupProd `
  -TemplateFile $templateFile `
  -TemplateParameterFile $parameterFile

Note

If the deployment failed, 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 groups from the Azure portal.

  1. Sign in to the Azure portal.
  2. From the left menu, select Resource groups.
  3. You see the two new resource groups you deployed in this tutorial.
  4. Select either resource group and view the deployed resources. Notice that they match the values you specified in your parameter file for that environment.

Clean up resources

  1. From the Azure portal, select Resource group from the left menu.
  2. Enter the resource group name in the Filter by name field. If you've completed this series, you have three resource groups to delete - myResourceGroup, myResourceGroupDev, and myResourceGroupProd.
  3. Select the resource group name.
  4. Select Delete resource group from the top menu.

Next steps

Congratulations, you've finished this introduction to deploying templates to Azure. Let us know if you have any comments and suggestions in the feedback section. Thanks!

The next tutorial series goes into more detail about deploying templates.