Five best practices for deploying Bicep templates using Azure PowerShell

6 mins read

Adopt best practices for Bicep deployments with PowerShell

As cloud engineers, we know the challenge of ensuring our colleagues follow and adopt best practices and processes when deploying our environment in Azure. Without the right baseline of practices, cloud engineers may face a range of challenges in provisioning cloud infrastructure.

That’s where best practices for Infrastructure-as-Code with Bicep come in. In this article, I will share with you five best practices for deploying Bicep templates using Azure PowerShell.

A great Infrastructure-as-Code solution enables DevOps teams to be able to plan smarter, collaborate better, and ship services faster and with minimal friction.

Bicep was born as an open-source, domain-specific language (DSL) to simplify your declarative deployment experience in Azure. Bicep sits on top of ARM templates. It provides a transparent, abstract layer and makes it much easier to read and write infrastructure-as-code in Azure.

That said, in order to use Azure PowerShell to work directly with Bicep files, you need to install the Bicep CLI.

Here are five best practices for deploying Bicep templates using Azure PowerShell:

1. Define the Deployment Scope.

If you want to deploy an App Service to Azure, probably you might want to target the deployment to a resource group.

Think of the scenario where you want to create three resource groups, and then deploy an App Service per resource group. In that case, you could target the deployment to a Subscription level.

Similar to ARM templates, you can target deployments to a resource group, subscription, management group, or tenant.

To target a resource group, use the cmdlet below:

New-AzResourceGroupDeployment -ResourceGroupName <resource-group-name> -TemplateFile <path-to-bicep>

To target a subscription, use the cmdlet below:

New-AzSubscriptionDeployment -Location <location> -TemplateFile <path-to-bicep>

To target a management group, use the cmdlet below:

New-AzManagementGroupDeployment -ManagementGroupId <management-group-id> -Location <location> -TemplateFile <path-to-bicep>

To target a tenant, use the cmdlet below:

New-AzTenantDeployment -Location <location> -TemplateFile <path-to-bicep>

Note we have to define the ‘Location’ if you deploy to any target other than the resource group.

2. Define the Deployment Name

Always define the deployment name. Provide a unique name for each deployment to quickly locate them afterward. Your team and colleagues will appreciate it.

The code below shows a quick option to create a unique name for your deployment.

$today=Get-Date -Format “MM-dd-yyyy”
New-AzResourceGroupDeployment -Name $deploymentName -ResourceGroupName YourResourceGroup -TemplateFile .appServicePlan.bicep

By using a unique name for your deployment, you can execute multiple deployments in parallel without overriding an existing execution of a deployment.

3. Use the What-IF operation to validate your Bicep template

Before you execute a deployment, you can preview the changes and the impact on your environment using the What-If operation.

Using What-If, Azure Resource Manager will provide you with a summary of the potential changes in your environment before you perform the execution of the deployment.

Here’s an example of how you can use the What-If operation when creating a Linux-based virtual machine in Azure using Bicep.

4. Structure your Bicep template parameters to support team collaboration.

Parameters help make Bicep templates reusable. Parameters can be used to customize the behavior of a deployment. Try to provide descriptions for your parameters as much as you can

To pass parameter values, you can use either inline parameters or a parameter file. Always use the ‘@secure()’ decorator to pass secrets or passwords in parameters.

You can also leverage other decorators to control the definition of the parameter value. Check this article on how you can adopt best practices for parameters in Bicep.

To pass inline parameters reference the ‘TemplateParameterFile’ as shown below:

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
-TemplateFile c:YourBicepTemplatesvnet.bicep `
-TemplateParameterFile c:YourBicepTemplatesvnet.parameters.json

To pass an external file you can reference the Uri:

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
-TemplateFile c:YourBicepTemplatesweb-app-sql-db.bicep `

5. Document common deployment errors and troubleshooting processes with Bicep

Address technical and organizational challenges in provisioning cloud infrastructure. While Bicep templates should be authored for flexibility, it is important to understand and document common errors in previous deployments and how any member of your team can overcome these challenges.

There is Microsoft documentation on the most common errors in ARM templates deployments.

It would be great to have similar documentation for Bicep, hope the Microsoft Azure team addresses this rather soon.


Adopting best practices is not only for large organizations, the earlier you adopt best practices for your Infrastructure-as-Code deployments in your organization, the earlier you will overcome potential challenges in provisioning cloud infrastructure.

Feel free to share what has worked best for you and feedback in the comments!

Join the AzInsider email list here.

-Dave R.

💪Five best practices for deploying Bicep templates using Azure PowerShell was originally published in CodeX on Medium, where people are continuing the conversation by highlighting and responding to this story.

Leave a Reply

Your email address will not be published.

Follow Us