How to deploy resources with Bicep and Azure CLI
This article explains how to use Azure CLI with Bicep files to deploy your resources to Azure. If you aren't familiar with the concepts of deploying and managing your Azure solutions, see Bicep overview.
You need a Bicep file to deploy. The file must be local.
You need Azure CLI and to be connected to Azure:
- Install Azure CLI commands on your local computer. To deploy Bicep files, you need Azure CLI version 2.20.0 or later.
- Connect to Azure by using az login. If you have multiple Azure subscriptions, you might also need to run az account set.
Samples for the Azure CLI are written for the bash
shell. To run this sample in Windows PowerShell or Command Prompt, you might need to change elements of the script.
If you don't have Azure CLI installed, you can use Azure Cloud Shell. For more information, see Deploy Bicep files from Azure Cloud Shell.
To deploy a Bicep file or ARM template, you need write access on the resources you're deploying and access to all operations on the Microsoft.Resources/deployments resource type. For example, to deploy a virtual machine, you need Microsoft.Compute/virtualMachines/write
and Microsoft.Resources/deployments/*
permissions. The what-if operation has the same permission requirements.
For a list of roles and permissions, see Azure built-in roles.
You can target your deployment to a resource group, subscription, management group, or tenant. Depending on the scope of the deployment, you use different commands.
To deploy to a resource group, use az deployment group create:
az deployment group create --resource-group <resource-group-name> --template-file <path-to-bicep>
To deploy to a subscription, use az deployment sub create:
az deployment sub create --location <location> --template-file <path-to-bicep>
For more information about subscription level deployments, see Create resource groups and resources at the subscription level.
To deploy to a management group, use az deployment mg create:
az deployment mg create --location <location> --template-file <path-to-bicep>
For more information about management group level deployments, see Create resources at the management group level.
To deploy to a tenant, use az deployment tenant create:
az deployment tenant create --location <location> --template-file <path-to-bicep>
For more information about tenant level deployments, see Create resources at the tenant level.
For every scope, the user deploying the Bicep file must have the required permissions to create resources.
You can deploy a Bicep file from your local machine or one that is stored externally. This section describes deploying a local Bicep file.
If you're deploying to a resource group that doesn't exist, create the resource group. The name of the resource group can only include alphanumeric characters, periods, underscores, hyphens, and parenthesis. It can be up to 90 characters. The name can't end in a period.
az group create --name ExampleGroup --location "Central US"
To deploy a local Bicep file, use the --template-file
switch in the deployment command. The following example also shows how to set a parameter value.
az deployment group create \
--name ExampleDeployment \
--resource-group ExampleGroup \
--template-file <path-to-bicep> \
--parameters storageAccountType=Standard_GRS
The deployment can take a few minutes to complete. When it finishes, you see a message that includes the result:
"provisioningState": "Succeeded",
Currently, Azure CLI doesn't support deploying remote Bicep files. You can use Bicep CLI to build the Bicep file to a JSON template, and then load the JSON file to the remote location. For more information, see Deploy remote ARM JSON templates.
To pass parameter values, you can use either inline parameters or a parameters file. The parameters file can be either a Bicep parameters file or a JSON parameters file.
To pass inline parameters, provide the values in parameters
. For example, to pass a string and array to a Bicep file in a Bash shell, use:
az deployment group create \
--resource-group testgroup \
--template-file <path-to-bicep> \
--parameters exampleString='inline string' exampleArray='["value1", "value2"]'
If you're using Azure CLI with Windows Command Prompt (CMD) or PowerShell, pass the array in the format: exampleArray="['value1','value2']"
.
You can also get the contents of file and provide that content as an inline parameter. Preface the file name with @.
az deployment group create \
--resource-group testgroup \
--template-file <path-to-bicep> \
--parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json
Getting a parameter value from a file is helpful when you need to provide configuration values. For example, you can provide cloud-init values for a Linux virtual machine.
The arrayContent.json format is:
[
"value1",
"value2"
]
To pass in an object, for example, to set tags, use JSON. For example, your Bicep file might include a parameter like this one:
"resourceTags": {
"type": "object",
"defaultValue": {
"Cost Center": "IT Department"
}
}
In this case, you can pass in a JSON string to set the parameter as shown in the following Bash script:
tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"
Use double quotes around the JSON that you want to pass into the object.
If you're using Azure CLI with Windows Command Prompt (CMD) or PowerShell, pass the object in the following format:
$tags="{'Owner':'Contoso','Cost Center':'2345-324'}"
az deployment group create --name addstorage --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags=$tags
You can use a variable to contain the parameter values. In Bash, set the variable to all of the parameter values and add it to the deployment command.
params="prefix=start suffix=end"
az deployment group create \
--resource-group testgroup \
--template-file <path-to-bicep> \
--parameters $params
However, if you're using Azure CLI with Windows Command Prompt (CMD) or PowerShell, set the variable to a JSON string. Escape the quotation marks: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'
.
The evaluation of parameters follows a sequential order, meaning that if a value is assigned multiple times, only the last assigned value is used. To ensure proper parameter assignment, it's advised to provide your parameters file initially and selectively override specific parameters using the KEY=VALUE syntax. It's important to mention that if you're supplying a bicepparam
parameters file, you can use this argument only once.
Rather than passing parameters as inline values in your script, you might find it easier to use a parameters file, either a Bicep parameters file or a JSON parameters file that contains the parameter values. The parameters file must be a local file. External parameters files aren't supported with Azure CLI. For more information about the parameters file, see Create Resource Manager parameters file.
With Azure CLI version 2.53.0 or later, and Bicep CLI version 0.22.X or higher, you can deploy a Bicep file by utilizing a Bicep parameter file. With the using
statement within the Bicep parameters file, there's no need to provide the --template-file
switch when specifying a Bicep parameter file for the --parameters
switch. Including the --template-file
switch will result in an "Only a .bicep template is allowed with a .bicepparam file" error.
The following example shows a parameters file named storage.bicepparam. The file is in the same directory where the command is run.
az deployment group create \
--name ExampleDeployment \
--resource-group ExampleGroup \
--parameters storage.bicepparam
The following example shows a parameters file named storage.parameters.json. The file is in the same directory where the command is run.
az deployment group create \
--name ExampleDeployment \
--resource-group ExampleGroup \
--template-file storage.bicep \
--parameters '@storage.parameters.json'
For more information about the parameters file, see Create Resource Manager parameters file.
You can use inline parameters and a location parameters file in the same deployment operation. For more information, see Parameter precedence.
Before deploying your Bicep file, you can preview the changes the Bicep file will make to your environment. Use the what-if operation to verify that the Bicep file makes the changes that you expect. What-if also validates the Bicep file for errors.
Currently, Azure CLI doesn't support creating template specs by providing Bicep files. However you can create a Bicep file with the Microsoft.Resources/templateSpecs resource to deploy a template spec. The Create template spec sample shows how to create a template spec in a Bicep file. You can also build your Bicep file to JSON by using the Bicep CLI, and then create a template spec with the JSON template.
When deploying a Bicep file, you can give the deployment a name. This name can help you retrieve the deployment from the deployment history. If you don't provide a name for the deployment, the name of the Bicep file is used. For example, if you deploy a Bicep file named main.bicep
and don't specify a deployment name, the deployment is named main
.
Every time you run a deployment, an entry is added to the resource group's deployment history with the deployment name. If you run another deployment and give it the same name, the earlier entry is replaced with the current deployment. If you want to maintain unique entries in the deployment history, give each deployment a unique name.
To create a unique name, you can assign a random number.
deploymentName='ExampleDeployment'$RANDOM
Or, add a date value.
deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")
If you run concurrent deployments to the same resource group with the same deployment name, only the last deployment is completed. Any deployments with the same name that haven't finished are replaced by the last deployment. For example, if you run a deployment named newStorage
that deploys a storage account named storage1
, and at the same time run another deployment named newStorage
that deploys a storage account named storage2
, you deploy only one storage account. The resulting storage account is named storage2
.
However, if you run a deployment named newStorage
that deploys a storage account named storage1
, and immediately after it completes you run another deployment named newStorage
that deploys a storage account named storage2
, then you have two storage accounts. One is named storage1
, and the other is named storage2
. But, you only have one entry in the deployment history.
When you specify a unique name for each deployment, you can run them concurrently without conflict. If you run a deployment named newStorage1
that deploys a storage account named storage1
, and at the same time run another deployment named newStorage2
that deploys a storage account named storage2
, then you have two storage accounts and two entries in the deployment history.
To avoid conflicts with concurrent deployments and to ensure unique entries in the deployment history, give each deployment a unique name.
- To understand how to define parameters in your file, see Understand the structure and syntax of Bicep files.