What is Bicep? The ARM Template DSL

[justinyoo]

Since this post, Bicep has got a lot of improvement and the new "refreshed" post is published here, Azure Bicep Refreshed. Please take a look at the new post.

Let's have a look at the Project Bicep and ARM Template Toolkit, and GitHub Actions for both.

• What is Bicep? The ARM Template DSL
• Linting Bicep Codes in DevOps Pipeline – ARM TTK
• Azure Bicep Refreshed

Microsoft has recently revealed an ARM Template DSL (Domain Specific Language), called Bicep to help devs build ARM templates quicker and easier.

There are several ways of provisioning resources onto Azure – via Azure Portal, or PowerShell or Azure CLI, or Azure SDKs in different languages, which all leverages Azure Resource Manager REST APIs. ARM template is one popular approach for DevOps engineers. However, many DevOps engineers have been providing feedback that ARM template is hard to learn and deploy at scales, as it can be tricky. Therefore, field experts like Microsoft MVPs have suggested many best practices about authoring ARM templates and share them through Azure Quickstart Templates or their own social platform. But it's still the big hurdle to get through.

As of this writing, it's v0.1, which is a very early preview. It means there will be many improvements until it becomes v1.0 including some potential breaking changes. Throughout this post, I'm going to discuss its expressions and how it can ease the ARM template authoring fatigues.

The sample .bicep file used for this post can be fount at this GitHub repository.

DO NOT USE BICEP ON YOUR PRODUCTION UNTIL IT GOES TO V0.3

ARM Template Skeleton Structure

ARM template is a JSON file that follows a specific format. A basic template looks like:

  {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {},
    "functions": {},
    "variables": {},
    "resources": [],
    "outputs": {}
  }

Those parameters, variables, resources and outputs attributes are as nearly as mandatory, so Bicep supports those attributes first. Due to this JSON syntax, there have been several issues for authoring.

• First, it's easy to incorrectly write the JSON template once the resource goes complex.
• Second, due to this complex structure, the readability gets dramatically reduced.
• Third but not the last, parameters, variables, resources and outputs MUST be defined within their declared sections, respectively, which is not as flexible as other programming languages.

But Bicep has successfully sorted out those issues. Let's have a look how Bicep copes with it.

Bicep Parameters

Parameters in Bicep can be declared like below. Every attribute is optional, by the way.

  param myParameter string {
    metadata: {
      description: 'Name of Virtual Machine'
    },
    secure: true
    allowed: [
      'abc'
      'def'
    ]
    default: abc
  }

The simplest form of the parameters can be like below. Instead of putting the metadata for the parameter description within the parameter declaration, we can simply use the comments (line #1). Also, instead of setting the default value inside the parameter declaration, assign a default value as if we do it in any programming language (line #7). Of course, we don't have to set a default value to the parameter (line #8).

  // Resource name
  param name string
  
  // Resource suffix
  param suffix string
  
  param location string = resourceGroup().location
  param locationCode string

On the other hands, to use secure or allowed attribute, the parameter should be declared as an object form (line #3-5).

  param virtualMachineAdminUsername string

  param virtualMachineAdminPassword string {
    secure: true
  }
  
  param virtualMachineSize string {
    allowed: [
      'Standard_D2s_v3'
      'Standard_D4s_v3'
      'Standard_D8s_v3'
    ]
    default: 'Standard_D8s_v3'
  }

Note that the parameter declaration is all about what type of value we will accept from outside, not what the actual value will be. Therefore, it doesn't use the equal sign (=) for the parameter declaration, except assigning its default value.

Bicep Variables

While the parameters accept values from outside, variables define the values to be used inside the template. The variables are defined like below. We can use all of existing ARM template functions to handle strings. But as Bicep supports string interpolations and ternary conditional operators, we can replace many concat() functions and if() functions with them (line #2-3).

  var metadata = {
    longName: '{0}-${name}-${locationCode}${coalesce(suffix, '') == '' ? '': concat('-', suffix)}'
    shortName: '{0}${replace(name, '-', '')}${locationCode}${coalesce(suffix, '') == '' ? '' : suffix}'
  }
  
  var storageAccount = {
    name: replace(metadata.shortName, '{0}', 'st')
    location: location
  }

Note that, unlike the parameters, the variables use the equal sign (=) because it assigns a value to the variable.

Bicep Resources

Bicep declares resources like below.

  resource st 'Microsoft.Storage/storageAccounts@2017-10-01' = {
    name: storageAccount.name
    location: storageAccount.location
    kind: 'StorageV2'
    sku: {
      name: 'Standard_LRS'
    }
  }
  
  resource vm 'Microsoft.Compute/virtualMachines@2018-10-01' = {
    name = resourceName
    location = resourceLocation
    ...
    properties: {
      ...
      diagnosticsProfile: {
        bootDiagnostics: {
          enabled: true
          storageUri: st.properties.primaryEndpoints.blob
        }
      }
    }
  }

There are several things worth noting.

• The format to declare a resource is similar to the parameter. The parameter declaration looks like param <identifier> <type>. The resource declaration looks similar to resource <identifier> <type>.
• However, the resource type section is way different from the parameter declaration. It has a definite format of <resource namespace>/<resource type>@<resource API version> (line #1).
  • I prefer to using the providers() function as I can't remember all the API versions for each resource.
  • But using the providers() function is NOT recommended. Instead, the API version should be explicitly declared. To find out the latest API version, use the following PowerShell command.

  $resourceType = @{ Label = "Resource Type"; Expression = { $_.ResourceTypes[0].ResourceTypeName } }
  $apiVersion = @{ Label = "API Version"; Expression = { $_.ResourceTypes[0].ApiVersions[0] } }
  Get-AzResourceProvider `
      -ProviderNamespace  `
      -Location  | `
      Select-Object $resourceType, $apiVersion | `
      Sort-Object -Property "Resource Type" | `
      Where-Object { $_."Resource Type" -eq "" }

• Bicep automatically resolves the dependencies between resources by using the resource identifier.
  • For example, the Storage Account resource is declared first as st, then st is referred within the Virtual Machine declaration (line #19).
  • On the other hands, in the ARM template world, we should explicitly declare resources within the dependsOn attribute to define dependencies.

You might have found an interesting fact while authoring Bicep file.

• ARM templates should rigorously follow the schema to declare parameters, variables and resources. Outside its respective section, we can't declare them.
• On the other hands, Bicep is much more flexible with regards to the location where to declare parameters, variables and resources.
  • We can simply declare param, var and resource wherever you like, within the Bicep file, then it's automagically sorted out during the build time.

Bicep Installation and Usage

As mentioned above, Bicep has just started its journey, and its version is v0.1, meaning there are a lot of spaces for improvements. Therefore, it doesn't have a straightforward installation process. But follow the installation guide, and you'll be able to make it. Once the installation completes, run the following command to build the Bicep file.

  bicep build ./azuredeploy.bicep

Rough Comparison to ARM Template Authoring

Let's compare the result between the original ARM template and Bicep-built ARM template. Both work the same, but the original file has 415 lines of code while Bicep-generated one cuts to 306 lines of the code. In addition to this, Bicep file itself is even as short as 288 lines of code. If I refactor more by simplifying all the variables, the size of the Bicep file will be much shorter.

---

So far, we have had a quick look at the early preview of the Bicep project. It was pretty impressive from the usability point of view and has improved developer experiences way better. Interested in trying out Bicep? You can take a first look with the Bicep Playground!

This article was originally published on Dev Kimchi.