Infrastructure as Code is a great tool to build and rebuild cloud resources. You can use ARM Template, Terraform, or Bicep, but one day or another you will fall into a problem; how can you share your code in a way people can understand and use it?
In Bicep, for example, you can write code in several different ways, and all these ways will work; I mean, it will create the resources you wanted in your Azure environment. But take the same code and send it to someone else working in a different team. You can be sure these people will call you back with multiple questions.
Take Bicep, we can share our Bicep code, it is easy, but are we sure that what we share is shareable? To be shareable every code, every Bicep project must speak for itself.
First, you will need to use GIT (or any other source control system), because you need to be able to control changes in your files and reverse any change.
You will need to use branch protection, you should not be able to push directly to the main branch. Instead, you should push to a separate branch when you modify your code and then create a pull request to the main branch, so any modifications can be reviewed and approved.
You will need to create a folder for each project with an explicit name, avoid naming your Bicep project project1, or database, use landingZoneWithFirewall for example.
In this folder, you will need to create a README.md file to summarize the project and any modifications.
Finally, your main Bicep code must be written in a main.bicep file.
At this point, we need to talk about parameters, variables, and resource symbolic names. To be understandable by everyone, these names should be as explicit as you can. Avoid names like, "VM", "StorageAccount", "r1", … Give the explicit name "webServerVM”.
And you should pay attention to the parameters. When you create a Bicep file, parameters are the key to customizing a deployment. Not only, parameters should have a very explicit name, but they should also come with several properties that make them understandable to anyone who uses it.
But if you want users to be autonomous and avoid team or Slack messages, you need to go beyond that. Your bicep code interacts with users through parameters.
The first step is to give clear, human-readable information about parameters. You can choose to use a comment or the description decorator.
@description('The Azure Policy Assignment Name')
param policyAssignmentName string // The Azure Policy Assignment Name
Try to use, when possible a default value for eligible parameters. Users will stay focused on their deployment while some will still have the possibility to customize the resources.
You can also use other decorators to limit what users can use. Decorators like allowed (list of allowed values), maxLength and minLength (size of string or array), maxVallue, and minValleu (for integer).
With this advice, you will provide a bicep template with options, predefined sets of values, and descriptions of what description of what is expected as value.
Another way to provide a great bicep template is to organize the code. Here are two approaches.
You can choose to group elements by type (First all parameters, second all variables, and finally resources and eventually output). This is great for understanding, but with large templates, it can become challenging to make any modifications, especially if you don't use modules.
The second option is to group bicep elements by resources or related resources. For example, if you need to deploy a VNET with some subnet and NSG, regroup parameters, variables, resources, and output in the same part of the file.
It is easier to work this way on a big template file especially if more than one person is engaged in the same project. It also opens the door to modules.
Modules in Bicep is a feature that offers you the possibility to reuse a portion of Bicep codes inside another Bicep file. As you may know, most IaC projects are very similar, you will have to deploy VNET and subnet, NSG, and peering, before deploying your core resources. See
These best practice tips will help you to go further during your journey in Bicep. It will help you to do better. Feel free to give me your advice in the comment section.
Top comments (1)
How are you doing version control?
Since it’s “infrastructure as a code” I think it’s reasonable to have version control and release management.
Myself, I use rush with custom commands and tags to display the currently deployed version of the service. Probably a bit “hacky” but didn’t come up with anything better🤷🏻♀️