All about Bicep & Deploying Bicep Files
Updated: Oct 3
Part 1 - You're reading it now!
Part 2 - Deploying Bicep with AZ CLI
Extra Credit - My Advanced Bicep Guide
Quick Primer on Bicep
When it comes to Infrastructure-as-Code (Iac) for Azure, there are two native solutions: the original option (ARM Templates), and the newer option (Bicep). Bicep uses its own Domain Specific Language (DSL) for deploying Azure resources declaratively. Bicep is more of a revision to the existing ARM template language, rather than an entirely new language.
While Bicep uses mostly all new syntax, the core functionality of ARM templates and the runtime remains the same. You have the same template functions, same resource declarations, etc.
Bicep is a transparent abstraction over ARM templates, which means anything that can be done in an ARM Template can be done in Bicep. All resource types, apiVersions, and properties that are valid in an ARM template are equally valid in Bicep, even on day one.
You can easily convert Bicep files to ARM Template JSON files. Likewise, you can also do the opposite, and convert ARM Template JSON files to Bicep files.
Bicep CLI
The Bicep CLI has quite a few different commands. I'll highlight some of the important ones below:
bicep build
The build command converts a Bicep file to an ARM Template JSON file. This is nice, however a lot of the deployment tools can already work directly with Bicep files (or they do the bicep-to-JSON conversion automatically for you). So, this command is only useful if you really need the ARM JSON version for some reason.
bicep build-params
Similar to the above, however, this converts a bicepparam parameters file to a JSON parameters file.
bicep decompile
The decompile command converts an ARM Template JSON file to a Bicep file. This is great if you have an existing library of ARM Templates that you'd like to convert to Bicep. This conversion is not 100% guaranteed and Microsoft warns that this may not always work as intended.
bicep decompile-params
Similar to the above, however, this attempts to convert a JSON parameters file to a bicepparam parameters file.
bicep format
The format command will automatically modify the given bicep file and apply the best standards for syntax and spacing. This is similar to the 'terraform fmt' command.
bicep generate-params
The generate-params command will automatically build a parameters file for you based on the given bicep file. You can configure it to output either in the old JSON parameters format or the new bicepparam parameters format.
bicep publish
The publish command will publish a Bicep file to a Bicep Module Registry. The Bicep CLI must be at version 0.4.1008 or later to use this command.
There are more, but I won't go into detail here. Please read the Microsoft documentation if you would like more information.
Bicep CLI (by way of the Azure CLI)
You can also use the Azure CLI to run Bicep commands, as the Azure CLI has built-in support for Bicep. But, how is Azure CLI able to run Bicep commands? Because it will automatically download the Bicep CLI for you. You must be using Azure CLI version 2.20.0 or later for this to work.
This will list out all of the currently available versions of the Bicep binary.
This will download the latest version of the Bicep binary to your computer. Depending on your OS, it will be placed in either %USERPROFILE%\.azure\bin or $HOME/.azure/bin
- Note 1: The Azure CLI will automatically download the binary when needed. So, this command is only needed if you want to manually download the binary first, or if you want to download a specific older version.
- Note 2: This folder is typically not in the operating system PATH, so just keep that in mind if you're trying to run the Bicep binary outside of the Azure CLI commands.
This will show the version of the Bicep binary that's been downloaded by the az cli.
If there is a newer version available, then this will download the latest version of the Bicep binary and it will overwrite the old binary.
This will remove the Bicep binary that was downloaded by the az cli.
az bicep build, decompile, publish, etc.
These commands operate the same way as the Bicep CLI commands.
Azure Deployment Scopes
This topic alone is very long and detailed. But, for the purposes of this article, I will keep it short and only highlight a few key areas.
Bicep templates can be deployed to 4 different Scopes:
Each Bicep file must have a line at the top that specifies the targetScope and it must be set to one of the 4 options above. However, there is an exception to this rule. If you omit the targetScope line in your Bicep file, then the default option of resourceGroup is automatically used.
Every Azure resource supports different deployment scopes. For example, an AKS Cluster only supports being deployed to the resourceGroup scope, whereas a Role Assignment supports being deployed to all 4 possible scopes. Check out the Bicep Template Reference to see which resources support which deployment scopes.
One last note, you can deploy to different scopes using the same bicep file. For example, if your Bicep file is scoped to managementGroup, then you can still deploy resources that are scoped to a resourceGroup. That being said, these other resources will need to be defined differently, by way of a Bicep Module. But, the point is that it's possible. More information can be found in the links in the References section at the end of this article.
Deploying Bicep using the Azure CLI
Azure CLI, starting with version 2.20.0, can be used to deploy Bicep files.
Deploy a Bicep file that has a targetScope of resourceGroup
Deploy a Bicep file that has a targetScope of subscription
Deploy a Bicep file that has a targetScope of managementGroup
Deploy a Bicep file that has a targetScope of tenant
Read Part 2 of this series for a full breakdown of using AZ CLI.
Deploying Bicep using the Az PowerShell Module
The Az PowerShell Module, starting with version 5.6.0, can be used to deploy Bicep files. Note: these commands will not work unless you already have the Bicep CLI installed on your system / available in your system's PATH.
Deploy a Bicep file that has a targetScope of resourceGroup
Deploy a Bicep file that has a targetScope of subscription
- Note: A common alias for this is: New-AzSubscriptionDeployment
New-AzManagementGroupDeployment
Deploy a Bicep file that has a targetScope of managementGroup
Deploy a Bicep file that has a targetScope of tenant
Read Part 3 of this series for a full breakdown of using Az PowerShell Module.
Deploying Bicep using Azure DevOps Pipelines
There is a Pipelines Task called AzureResourceManagerTemplateDeployment and it will let you deploy both ARM Templates and Bicep Templates. Support for Bicep files was added to this Task as of version 3.199.0.
Read Part 4 of this series for a full breakdown of using Azure DevOps Pipelines.
Deploying Bicep using GitHub Actions
There is a GitHub Action called azure/arm-deploy and it will let you deploy both ARM Templates and Bicep Templates.
I will go into more detail on this action in a future article.
I've only just scratched the surface of Bicep and how to deploy. Further entries in this series can be found below.
My Bicep Deployment series:
Part 1 - You're reading it now!
Part 2 - Deploying Bicep with AZ CLI
Extra Credit - My Advanced Bicep Guide
References
- Resource group deployments with Bicep files
- Subscription deployments with Bicep files
- Management group deployments with Bicep files