top of page
Search
  • Writer's pictureNathan
    • Apr 10, 2022

Deploying Bicep Files Part 3 - Az PowerShell Module

Updated: Aug 27, 2022

If you haven't already, please check out the previous parts of this series.


Deploying Bicep with Az PowerShell Module

PowerShell does not have out-of-the-box support to deploy Bicep files. You must first install the Az PowerShell Module. As you can see from the link, the command to install the module is Install-Module -Name Az and this will install directly from the PowerShell Gallery. After the module is installed, you will then have access to the necessary PowerShell cmdlets that are described below. On top of that, the PowerShell cmdlets won't work unless you also have the Bicep CLI installed on your system and available somewhere in your system's PATH.


If you need a quick primer on PowerShell, make sure to check out my article.

 

New-AzResourceGroupDeployment

This command lets you deploy a Bicep file that has a targetScope set to resourceGroup. Remember, if your Bicep file does not have a targetScope line at the top, then by default, the value of resourceGroup is automatically used. Let's go over the options available with this command:

  • -ResourceGroupName <rgName>

    • This specifies the Resource Group to deploy into. This must already exist

  • -Mode <option>

    • <option> can be either Incremental or Complete

    • This is optional. If omitted, then Incremental is used

    • Incremental simply deploys the resources that are defined in your Bicep file. It doesn't care what other resources may reside in the Resource Group

    • Complete mode uses the Bicep file as the ultimate source of truth. Be careful with this option. If you have existing resources in the Resource Group, and those existing resources are not defined in your Bicep file, then those existing resources will be deleted. Likewise, if you remove a resource's code from your Bicep file, then that resource will be deleted from the Resource Group

  • -RollbackToLastDeployment -RollbackDeploymentName <deploymentName>

    • When there's an error, roll back to the last successful deployment

    • Or, roll back to a specific deployment on error

Wait, how do I specify which Subscription to deploy to? Well, the currently selected subscription will be used automatically. You can set your subscription using Set-AzContext -Subscription <subscriptionNameOrId>


Note: Deployment data is automatically stored in the same Region as the Resource Group specified with the -ResourceGroupName parameter. There is no way to change this for the New-AzResourceGroupDeployment command.

 

New-AzDeployment

This command lets you deploy a Bicep file that has a targetScope set to subscription. There is a common alias for this cmdlet that you may also use: New-AzSubscriptionDeployment


Let's go over the options available with this command:

  • -Location <locationName>

    • This is the region used to store data about your deployment

Wait, how do I specify which Subscription to deploy to? Well, the currently selected subscription will be used automatically. You can set your subscription using Set-AzContext -Subscription <subscriptionNameOrId>

 

New-AzManagementGroupDeployment

This command lets you deploy a Bicep file that has a targetScope set to managementGroup. Let's go over the options available with this command:

  • -Location <locationName>

    • This is the region used to store data about your deployment

  • -ManagementGroupId <managementGroupID>

    • This specifies the Management Group to deploy to

 

New-AzTenantDeployment

This command lets you deploy a Bicep file that has a targetScope set to tenant. Let's go over the options available with this command:

  • -Location <locationName>

    • This is the region used to store data about your deployment

Wait, how do I specify which Tenant to deploy to? Well, the currently selected tenant will be used automatically. You can set your tenant using Set-AzContext -Tenant <tenantDomainOrId>

 

Options that are common to all 4 Az PowerShell cmdlets

  • -Name <deploymentName>

    • This specifies the name for this deployment. You may need to reference this deployment in the future, so it can be beneficial to use good names here

    • This is optional. If omitted, then the name of the Bicep file is used as the name of the deployment

    • If you use the same deployment name over and over, then you will be restricted to viewing information about the latest deployment only. In other words, new deployments will overwrite the deployment data of old deployments if you use the same deployment name

  • -TemplateFile <localFile.bicep>

    • This specifies the local path to the bicep file you want to deploy

    • Either this or -TemplateUri is required

  • -TemplateParameterFile <localParameters.json>

    • This specifies the local path to a parameters file to use for this deployment

    • This is optional. Either you deployment doesn't need parameters or you're supplying parameters in a different way

  • -TemplateUri <https://remote/file.bicep>

    • This specifies the URI to the bicep file you want to deploy

    • Either this or -TemplateFile is required

  • -TemplateParameterUri <https://remote/parameters.json>

    • This specifies the URI to a parameters file to use for this deployment

    • This is optional. Either your deployment doesn't need parameters or you're supplying parameters in a different way

  • -parameterKey parameterValue

    • This let's you provide parameter values to your Bicep template directly on the command line

    • Multiple instances of this can be used on the same command, for example: -key1 value1 -key2 value2

    • Parameter values entered this way take precedence over values supplied with -TemplateParameterFile or -TemplateParameterUri

    • This is optional. Either your deployment doesn't need parameters or you're supplying parameters in a different way

  • -WhatIf

    • This will not deploy any resources. Instead, it will show you a summary of the changes that this template wants to make

    • This is similar to a terraform plan command

  • -Confirm

    • This will first run a what-if (see above) and show you the results. Then, it will prompt you to accept the changes before continuing the deployment

    • -ProceedIfNoChange

      • This is an optional parameter that can be used when you specify the -Confirm parameter

      • This tells the deployment to automatically continue if the what-if result contains zero changes

 

Examples of minimal deployment commands

 

Well, that covers most of the basics of deploying Bicep files with the Az PowerShell Module. There are still a lot of details that I didn't expand upon in this article. For example, there are other ways to define your Bicep template, such as Template Specs and Template Objects. Make sure to read the Microsoft docs for more information.


The next part in this series will cover deploying Bicep files using the Azure DevOps Pipelines task. Stay tuned!

 

My Bicep Deployment series:

1,085 views
bottom of page