Parameters in Bicep

This article describes how to define and use parameters in a Bicep file. By providing different values for parameters, you can reuse a Bicep file for different environments.

Resource Manager resolves parameter values before starting the deployment operations. Wherever the parameter is used, Resource Manager replaces it with the resolved value.

Each parameter must be set to one of the data types.

You're limited to 256 parameters in a Bicep file. For more information, see Template limits.

For parameter best practices, see Parameters.

Training resources

If you would rather learn about parameters through step-by-step guidance, see Build reusable Bicep templates by using parameters.

Declaration

Each parameter has a name and data type. Optionally, you can provide a default value for the parameter.

param <parameter-name> <parameter-data-type> = <default-value>

A parameter can't have the same name as a variable, resource, output, or other parameter in the same scope.

The following example shows basic declarations of parameters.

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

The param keyword is also used in .bicepparam files. In .bicepparam files, you don't need to specify the data type as it is defined in Bicep files.

param <parameter-name> = <value>

For more information, see Parameters file.

User-defined type expressions can be used as the type clause of a param statement. For example:

param storageAccountConfig {
  name: string
  sku: string
}

For more information, see User-defined data types.

Default value

You can specify a default value for a parameter. The default value is used when a value isn't provided during deployment.

param demoParam string = 'Contoso'

You can use expressions with the default value. Expressions aren't allowed with other parameter properties. You can't use the reference function or any of the list functions in the parameters section. These functions get the resource's runtime state, and can't be executed before deployment when parameters are resolved.

param location string = resourceGroup().location

You can use another parameter value to build a default value. The following template constructs a host plan name from the site name.

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

However, you can't reference a variable as the default value.

Decorators

Parameters use decorators for constraints or metadata. The decorators are in the format @expression and are placed above the parameter's declaration. You can mark a parameter as secure, specify allowed values, set the minimum and maximum length for a string, set the minimum and maximum value for an integer, and provide a description of the parameter.

The following example shows two common uses for decorators.

@secure()
param demoPassword string

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

The following table describes the available decorators and how to use them.

Decorators are in the sys namespace. If you need to differentiate a decorator from another item with the same name, preface the decorator with sys. For example, if your Bicep file includes a parameter named description, you must add the sys namespace when using the description decorator.

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

The available decorators are described in the following sections.

Secure parameters

You can mark string or object parameters as secure. The value of a secure parameter isn't saved to the deployment history and isn't logged.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Allowed values

You can define allowed values for a parameter. You provide the allowed values in an array. The deployment fails during validation if a value is passed in for the parameter that isn't one of the allowed values.

@allowed([
  'one'
  'two'
])
param demoEnum string

If you define allowed values for an array parameter, the actual value can be any subset of the allowed values.

Length constraints

You can specify minimum and maximum lengths for string and array parameters. You can set one or both constraints. For strings, the length indicates the number of characters. For arrays, the length indicates the number of items in the array.

The following example declares two parameters. One parameter is for a storage account name that must have 3-24 characters. The other parameter is an array that must have from 1-5 items.

@minLength(3)
@maxLength(24)
param storageAccountName string

@minLength(1)
@maxLength(5)
param appNames array

Integer constraints

You can set minimum and maximum values for integer parameters. You can set one or both constraints.

@minValue(1)
@maxValue(12)
param month int

Description

To help users understand the value to provide, add a description to the parameter. When a user deploys the template through the portal, the description's text is automatically used as a tip for that parameter. Only add a description when the text provides more information than can be inferred from the parameter name.

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

Markdown-formatted text can be used for the description text:

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

When you hover your cursor over storageAccountName in VS Code, you see the formatted text:

Make sure the text follows proper Markdown formatting; otherwise, it may not display correctly when rendered

Metadata

If you have custom properties that you want to apply to a parameter, add a metadata decorator. Within the metadata, define an object with the custom names and values. The object you define for the metadata can contain properties of any name and type.

You might use this decorator to track information about the parameter that doesn't make sense to add to the description.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

When you provide a @metadata() decorator with a property that conflicts with another decorator, that decorator always takes precedence over anything in the @metadata() decorator. So, the conflicting property within the @metadata() value is redundant and will be replaced. For more information, see No conflicting metadata.

Use parameter

To reference the value for a parameter, use the parameter name. The following example uses a parameter value for a key vault name.

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

Objects as parameters

It can be easier to organize related values by passing them in as an object. This approach also reduces the number of parameters in the template.

The following example shows a parameter that is an object. The default value shows the expected properties for the object. Those properties are used when defining the resource to deploy.

param vNetSettings object = {
  name: 'VNet1'
  location: 'eastus'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2020-06-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

Next steps

• To learn about the available properties for parameters, see Understand the structure and syntax of Bicep files.
• To learn about passing in parameter values as a file, see Create a Bicep parameter file.
• To learn about providing parameter values at deployment, see Deploy with Azure CLI, and Deploy with Azure PowerShell.