Flexing your bicep

If you ever worked with ARM templates, you will know that they are not the easiest dragon to slay. Once you get used to working with them, it gets a bit easier and extensions in for example VS Code can make life a bit easier too. But any project where you do more than just creating a couple of resources quickly turns into lines and lines of json. It get’s hard to author or troubleshoot.

Enter Project Bicep!

To quote the readme from the Project Bicep pages on github:

Bicep is a Domain Specific Language (DSL) for deploying Azure resources declaratively. It aims to drastically simplify the authoring experience with a cleaner syntax, improved type safety, and better support for modularity and code re-use. Bicep is a transparent abstraction over ARM and ARM templates, which means anything that can be done in an ARM Template can be done in Bicep (outside of temporary known limitations). All resource types, apiVersions, and properties that are valid in an ARM template are equally valid in Bicep on day one.

Bicep code is transpiled to standard ARM Template JSON files, which effectively treats the ARM Template as an Intermediate Language (IL).

In other words, bicep should help us making more readable code which is hopefully easier to troubleshoot. With the release of version 0.3 bicep is now also officially supported (though it’s still in preview):

As of v0.3, Bicep is now supported by Microsoft Support Plans and Bicep has 100% parity with what can be accomplished with ARM Templates. As of this writing, there are no breaking changes currently planned, but it is still possible they will need to be made in the future.

Which seemed to me like a good time to start familiarize myself with it and see where it can take me. First thing to do is to get the right tools. Check the installing documentation on the Project site for more information but basically it comes down to installing bicep.exe (I used the manual PowerShell option) and the bicep extension for VS Code.

The Project site contains a tutorial which will get you started.

My first impression of bicep is pretty good. I did run into two bugs while doing the tutorial, but either does not appear to be anything major. I do like how it allows you to write more clean code and with the use of modules you should be able to break up your code into smaller, more manageable (and readable) pieces.

I guess soon I will have to find an example project to create for myself to get some real handson experience with bicep, rather than typing over (or copying) the provided examples.

While I was doing the tutorial, I did run into two little bugs, both while doing the modules part of the tutorial:

First bug:

New-AzureResourceGroupDeployment error when deploying a bicep file which uses modules

At first I was a little thrown by the error as it is not quite clear what the problem is. Also a google search did not immediately reveal a solution. However, when I checked on github someone had just logged an issue for the same problem: #1857

So apparently I am not alone :wink:. Either building the ARM template first with bicep.exe or using Az Cli to deploy the .bicep file directly works, so there is that.

Second bug:

Another bug I ran into, also on the modules tutorial, is probably a typo in the documentation (By now I switched to using Az Cli for deployment because of Bug 1): ‘Az deployment sub create’ error when using the original example

Since I have never done an authorization deployment through ARM yet it took me a little while to find the problem. It appears that

properties: {
    roleDefinitionId: contributor
    principalId: objectId
}

should be:

properties: {
    roleDefinitionId: 
        '${subscriptionResourceId('Microsoft.Authorization/roleDefinitions', contributor)}'
    principalId: objectId
}

In any case, the latter code makes the deployment work while the first one fails.