Edit

Tutorial: Deploy and troubleshoot a Bicep template with Azure CLI (preview)

In this tutorial, you use Azure CLI preview to deploy infrastructure as code safely: you preview what a Bicep template changes before you deploy it, confirm that deploying it again doesn't create duplicate resources, and get actionable diagnostics when a deployment fails.

When you finish, the template has created exactly one storage account with the intended settings, a repeat deployment has left that storage account unchanged, a controlled failure has produced a clear error, and no test resources remain.

In this tutorial, you:

  • Prepare the deployment
  • Preview the change
  • Deploy and inspect
  • Repeat the deployment
  • Diagnose a failure
  • Clean up

Prerequisites

Deploy in Incremental mode into a dedicated resource group, not against shared resources.

You need an Azure subscription. If you don't have one, create a free account.

Create the Bicep template

Save the following resource-group-scoped template as sample-storage.bicep. Set the template path in the next section to this local file. The template disables anonymous blob access and shared-key authorization and requires HTTPS with TLS 1.2 or later.

targetScope = 'resourceGroup'

@description('Globally unique storage account name.')
param storageAccountName string

@description('Storage account location.')
param location string = resourceGroup().location

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    minimumTlsVersion: 'TLS1_2'
    supportsHttpsTrafficOnly: true
    allowBlobPublicAccess: false
    allowSharedKeyAccess: false
  }
}

output storageAccountId string = storageAccount.id

Set variables

sub="<test-subscription-id>"
location="<region>"
template="<path-to-sample-storage.bicep>"
run=$(date +%Y%m%d%H%M%S)
rg="azclips-iac-$run"
deployment="deploy-$run"
storage="clips$(openssl rand -hex 9)"

Prepare the deployment

az group create --subscription-id "$sub" --name "$rg" --location "$location"
az group update --subscription-id "$sub" --name "$rg" --tags purpose=iac-review
az group show --subscription-id "$sub" --name "$rg"

az group create doesn't accept tags, so az group update adds the purpose tag after the group exists. The az group show output includes "provisioningState": "Succeeded" and the tag "purpose": "iac-review".

Preview the change

az deployment group what-if --subscription-id "$sub" --resource-group "$rg" --name "$deployment" --template-file "$template" --parameter "storageAccountName=$storage" --mode Incremental

What-if doesn't change any resources. Its output lists one change, a Create for the storage account, with the properties from the template. If the output lists other changes, review them before you deploy.

Deploy and inspect

first_id=$(az deployment group create --subscription-id "$sub" --resource-group "$rg" --name "$deployment" --template-file "$template" --parameter "storageAccountName=$storage" --validation-level Provider --mode Incremental --query properties.outputs.storageAccountId.value --output tsv)
echo "$first_id"
az deployment group show --subscription-id "$sub" --resource-group "$rg" --name "$deployment" --query properties.provisioningState --output tsv
az deployment group list --subscription-id "$sub" --resource-group "$rg" --output table

az deployment group create waits for the deployment to finish. The first command prints the resource ID of the new storage account, the deployment's provisioning state is Succeeded, and the deployment list shows one deployment.

Repeat the deployment

In practice, you redeploy the same template whenever you rerun a pipeline, retry after a transient failure, or apply a change to the template. Incremental deployments are idempotent: deploying the same template with the same parameters updates the existing resources to match the template instead of creating new ones. Deploy again and confirm that the storage account is the same one.

second_id=$(az deployment group create --subscription-id "$sub" --resource-group "$rg" --name "$deployment" --template-file "$template" --parameter "storageAccountName=$storage" --validation-level Provider --mode Incremental --query properties.outputs.storageAccountId.value --output tsv)
if [ "$first_id" = "$second_id" ]; then echo "Same storage account"; else echo "Storage account changed" >&2; fi

The output is Same storage account. The second deployment succeeds and returns the same resource ID, so no second storage account was created.

Diagnose a failure

Submit a deployment with an invalid mode to see how the CLI reports an error.

if az deployment group create --subscription-id "$sub" --resource-group "$rg" --name "$deployment-invalid" --template-file "$template" --parameter "storageAccountName=$storage" --mode Foo; then
  echo "The invalid deployment unexpectedly succeeded." >&2
fi

The command fails with a nonzero exit code and an error that lists the allowed values for --mode, Incremental and Complete. Because the CLI rejects the value before it submits the deployment, no deployment named <deployment>-invalid is created.

When a deployment that Azure accepts fails later, list the failed deployments and show the error details:

az deployment group list --subscription-id "$sub" --resource-group "$rg" --filter "provisioningState eq 'Failed'" --output table
az deployment group show --subscription-id "$sub" --resource-group "$rg" --name "<failed-deployment-name>" --query properties.error

The error object contains the error code and message that Azure Resource Manager returned. To find the resource that failed, list the deployment's individual operations:

az deployment operation group list --subscription-id "$sub" --resource-group "$rg" --name "<failed-deployment-name>"

Each operation in the output includes its provisioning state, target resource, and status code and message. The failed operation identifies the resource and the error that stopped the deployment.

Clean up resources

az group delete --subscription-id "$sub" --name "$rg"
az group exists --subscription-id "$sub" --name "$rg"

az group delete waits until the resource group and the storage account are deleted. az group exists then returns false.

Other deployment scopes

Repeat the preview, deploy, inspect and clean-up steps at a broader scope, using a template written for that scope. Use test scopes and uniquely named resources. Deleting the resource group doesn't remove resources deployed at a higher scope, so remove those resources individually.

Each scope has its own command group. Unlike resource group deployments, these commands require --location, which is where Azure Resource Manager stores the deployment data.

Scope Command group Scope parameter
Subscription az deployment sub --subscription-id (defaults to the active profile's subscription)
Management group az deployment mg --management-group-id
Tenant az deployment tenant None

Each group provides what-if, create, show, and list commands, and az deployment operation sub, mg, and tenant list the operations at each scope. For example, to preview and deploy a subscription-scoped template:

az deployment sub what-if --subscription-id "$sub" --location "$location" --name "sub-$run" --template-file "<path-to-subscription-template.bicep>"
az deployment sub create --subscription-id "$sub" --location "$location" --name "sub-$run" --template-file "<path-to-subscription-template.bicep>"

Tenant-scoped deployments always use Incremental mode.