Tutorial: Use parameter files to deploy Azure Resource Manager Bicep file

  • Article

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 Bicep file, 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. You use the same JSON parameter file as you deploy a JSON template. In this tutorial, you'll create parameter files for development and production environments. It takes about 12 minutes to complete.

Note

This article contains Bicep examples. Bicep is currently in preview. For more information, see Project Bicep.

Prerequisites

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

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

Review Bicep file

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

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Premium_LRS'
])
param storageSKU string = 'Standard_LRS'

param location string = resourceGroup().location
param appServicePlanName string = 'exampleplan'

@minLength(2)
@description('Base name of the resource such as web app name and app service plan.')
param webAppName string

@description('The Runtime stack of current web app.')
param linuxFxVersion string = 'php|7.0'

param resourceTags object = {
  Environment: 'Dev'
  Project: 'Tutorial'
}

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'
var webAppPortalName = '${webAppName}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2019-04-01' = {
  name: uniqueStorageName
  location: location
  tags: resourceTags
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

resource appPlan 'Microsoft.Web/serverfarms@2016-09-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'B1'
    tier: 'Basic'
    size: 'B1'
    family: 'B'
    capacity: 1
  }
  kind: 'linux'
  properties: {
    perSiteScaling: false
    reserved: true
    targetWorkerCount: 0
    targetWorkerSizeId: 0
  }
}

resource site 'Microsoft.Web/sites@2016-08-01' = {
  name: webAppPortalName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appPlan.id
    siteConfig: {
      linuxFxVersion: linuxFxVersion
    }
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

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

Add parameter files

Parameter files are JSON files with a structure that is similar to JSON templates. 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 Bicep file. The name of each parameter in your parameter file must match the name of a parameter in your Bicep file. The name is case-insensitive but to easily see the matching values we recommend that you match the casing from the Bicep file.

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 Bicep file. 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 Bicep file

Use either Azure CLI or Azure PowerShell to deploy the Bicep file.

In this tutorial, 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-bicep-file}, {path-to-azuredeploy.parameters.dev.json}, {path-to-azuredeploy.parameters.prod.json}, and the curly braces {} with your Bicep file and parameter file paths.

First, we'll deploy to the dev environment.

To run this deployment cmdlet, you must have the latest version of Azure PowerShell.

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

Now, we'll deploy to the production environment.

$parameterFile="{path-to-azuredeploy.parameters.prod.json}"
New-AzResourceGroup `
  -Name myResourceGroupProd `
  -Location "China North"
New-AzResourceGroupDeployment `
  -Name prodenvironment `
  -ResourceGroupName myResourceGroupProd `
  -TemplateFile $bicepFile `
  -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.
  3. Select the resource group name.
  4. Select Delete resource group from the top menu.

Next steps

In this tutorial, you use a parameter file to deploy your Bicep file. In the next tutorial, you'll learn how to modularize your Bicep files.

Add modules