Tips for writing Bicep files for Azure deployment

In the last few months, I've gotten very into the world of deploying apps to Azure using Bicep files, and I probably spend more time writing Bicep than Python lately. Bicep is a declarative language for describing the Azure resources that should be provisioned. It's similar to Terraform, but is specific to Azure.

I love the end result of Bicep: a highly replicable deploy to multiple interdependent resources with custom configurations. However, the journey isn't always so fun, since it's often not clear how to write Bicep to achieve the desired result. I'm writing up my tips for Bicep file writing to help others. Let me know if you have any to add!

Install the Bicep extension

I use VS Code when writing Bicep files (since I use VS Code for nearly everything these days), and it fortunately has a Bicep extension. The extension will add syntax highlighting to your files, point out in real-time when something isn't correct, and it even includes a snippet feature (which I haven't used personally).

Open the Bicep reference

I don't recommend the Bicep reference for leisure reading, but it's always good to check the authoritative source. I typically find the right page by searching the web for a specific resource, like "Azure Bicep reference Key Vault" or if I know it, referencing the namespace "Azure Bicep reference Microsoft.Web/sites", which brings me to this page. Each reference page has an example with all the properties, then descriptions for each property, and at the very botton, a bunch of examples available in both ARM/Bicep.

Find related samples

My general approach for programming is to find something that's as close as possible to what I want to do, and then tweak it from there. My favorite source for samples is the AZD Templates Gallery, since you can filter by language, framework, or Azure resource. Use the AND/OR toggle in the top right to change how the filtering works. Once you find an appropriate sample, find the infra folder in the Github repo and see how it's written. Another source of samples is the Bicep reference, as I just mentioned.

Search Github for examples

If I still can't find a sample that shows what I'm looking for, I turn to Github code search. There's a fancy new code search in beta now, but the old code search is good enough for our purposes. I typically search for either a resource namespace or a particular configuration property name, and then I add on either "lang:bicep" or "path:bicep". The "lang" searches for files tagged as the Bicep language, while path searches for files that contain bicep in the path. Probably "lang:bicep" is the more proper filter to use. So my full search might be "Microsoft.Web/sites lang:bicep" or "appCommandLine lang:bicep". Keep in mind that you may find samples using deprecated settings, but you can cross-check with the reference to make sure they're modern.

Generate with NubesGen

NubesGen is a tool built by some of my Cloud Advocacy teammates. You tick a few boxes describing the app you're trying to make, and NubesGen will create the configuration files for you. It doesn't include every Azure resource ever, but it does include the most commonly used services. Since it's open source, so you can file requests or submit pull requests to add more options. You can also browse out its Bicep templates to see how it builds out the final Bicep files.

Create the resource manually

Sometimes I'm trying to Bicep-ify an app I've already deployed another way, like via the VS Code extension or AZ CLI commands. In that case, I open the existing resources in the Azure Portal and either:

• Select "JSON view" from a specific resource's Overview page, and search through that JSON for the setting I'm interested in.
• Use "Export template" on either the entire resource group or a particular resource, which downloads an ARM JSON file. I can search through that JSON or decompile it into a Bicep. This is often my last resort, because exporting the ARM for an entire resource group takes a decent amount of time and often creates a bunch of unnecessary ARM cruft. It is not the minimal configuration needed to create that resource (more like the maximal!). It's a good tool to have in the toolbox though, just in case.

I will also often create a single resource from scratch in the Azure Portal, like a PostgreSQL server, just so I can see the default configuration. That way, I know what I actually need to override in my own Bicep file, and what I can leave out, if I'm happy with the default value.

Ask the mailing list

If you are a Microsoft employee, there's an "ARM-Bicep Deployment Experts" mailing list which fields lots of questions each week. You can sort through the archives or ask your question if it's never been asked. If you're not a MS employee, then you can post on StackOverflow and add the azure-bicep tag.