Understanding Bicep File Structure and Syntax

Understanding Bicep File Structure and Syntax

Bicep is a domain-specific language (DSL) for declaring Azure resources in a more readable and concise way than traditional ARM templates (JSON). It compiles into an ARM JSON template and is designed to be easier to author, read, and maintain.

Let’s break down the essential components and syntax of a Bicep file.

1. Bicep File Structure

A basic Bicep file typically consists of the following sections:

1. Scope: Defines the scope of resource deployment (e.g., subscription, resource group, management group).

2. Parameters: Allow the user to pass values into the template during deployment.

3. Variables: Used to store values that are computed during the deployment and are used throughout the template.

4. Resources: Defines the Azure resources to be deployed.

5. Modules: Enables reusability by calling other Bicep files or templates.

6. Outputs: Used to return values from the Bicep deployment.

7. Other Features: Such as loops, conditional deployments, multiline strings, referencing existing resources, and more.

2. Sample Bicep File

Below is a sample.bicep file, which deploys a Virtual Network (vNet) with some configurable parameters and outputs.

xxxxxxxxxx
30
1
// Parameters section
2
param location string = 'East US'
3
param vnetName string = 'myVNet'
4
param subnetName string = 'mySubnet'
5
// Variables section
6
var addressPrefix = '10.0.0.0/16'
7
var subnetPrefix = '10.0.1.0/24'
8
// Resource section - Creating the Virtual Network
9
resource vnet 'Microsoft.Network/virtualNetworks@2020-05-01' = {
10
  name: vnetName
11
  location: location
12
  properties: {
13
    addressSpace: {
14
      addressPrefixes: [
15
        addressPrefix
16
      ]
17
    }
18
  }
19
}
20
// Resource section - Creating a Subnet within the Virtual Network
21
resource subnet 'Microsoft.Network/virtualNetworks/subnets@2020-05-01' = {
22
  name: '${vnetName}/${subnetName}'
23
  parent: vnet
24
  properties: {
25
    addressPrefix: subnetPrefix
26
  }
27
}
28
// Outputs section
29
output vnetId string = vnet.id
30
output subnetId string = subnet.id

Breakdown of the Sample Bicep File:

1. Parameters Section:

   • param: Defines the input parameters for the deployment. Parameters allow you to reuse the Bicep file for different environments or configurations.

   • Example: param location string = 'East US' defines a string parameter location with a default value of East US.

2. Variables Section:

   • var: Defines local variables that are used in the Bicep file. Variables are evaluated during the compilation of the template.

   • Example: var addressPrefix = '10.0.0.0/16' creates a variable for the address prefix used in the virtual network.

3. Resources Section:

   • resource: Defines the Azure resources that will be created. Each resource is defined with its type, API version, and properties.

   • Example: resource vnet 'Microsoft.Network/virtualNetworks@2020-05-01' defines a virtual network resource with a specified name, location, and address space.

4. Outputs Section:

   • output: Defines the output values from the deployment. Outputs can be used to return resource identifiers, such as the ID of the virtual network or subnet.

   • Example: output vnetId string = vnet.id returns the ID of the vnet resource.

3. Detailed Breakdown of Key Components

a. Scope

The scope defines where the resources will be deployed. By default, the scope of the deployment is set to the resource group. However, you can specify other scopes like subscription or management group.

Resource Group Scope (Default):

xxxxxxxxxx
4
1
resource myVnet 'Microsoft.Network/virtualNetworks@2020-05-01' = {
2
  name: 'myVnet'
3
  location: resourceGroup().location  // Use the location of the resource group
4
}

Subscription Scope:

xxxxxxxxxx
5
1
resource myVnet 'Microsoft.Network/virtualNetworks@2020-05-01' = {
2
  scope: subscription()
3
  name: 'myVnet'
4
  location: 'East US'
5
}

Management Group Scope:

xxxxxxxxxx
5
1
resource myVnet 'Microsoft.Network/virtualNetworks@2020-05-01' = {
2
  scope: managementGroup('myManagementGroup')
3
  name: 'myVnet'
4
  location: 'East US'
5
}

b. Parameters

Parameters are used to accept values during the deployment and allow customization of resources. You can specify types, defaults, and descriptions for parameters.

Syntax:

xxxxxxxxxx
1
1
param parameterName parameterType = defaultValue

Example:

xxxxxxxxxx
8
1
param location string = 'East US' // Default value is 'East US'
2
param vmSize string {
3
  type: string
4
  defaultValue: 'Standard_DS1_v2'
5
  metadata: {
6
    description: 'The size of the Virtual Machine.'
7
  }
8
}

c. Variables

Variables are defined in the var section and can be used to store values that are evaluated when the Bicep file is compiled. Variables are not passed during deployment like parameters.

Syntax:

xxxxxxxxxx
1
1
var variableName = value

Example:

xxxxxxxxxx
2
1
var addressPrefix = '10.0.0.0/16'
2
var subnetPrefix = '10.0.1.0/24'

d. Resources

A Bicep file defines Azure resources using the resource keyword. Resources are defined with their type, API version, name, and properties.

Syntax:

xxxxxxxxxx
7
1
resource resourceName 'resourceType@apiVersion' = {
2
  name: 'resourceName'
3
  location: 'location'
4
  properties: {
5
    // resource properties
6
  }
7
}

Example:

xxxxxxxxxx
11
1
resource vnet 'Microsoft.Network/virtualNetworks@2020-05-01' = {
2
  name: 'myVNet'
3
  location: 'East US'
4
  properties: {
5
    addressSpace: {
6
      addressPrefixes: [
7
        '10.0.0.0/16'
8
      ]
9
    }
10
  }
11
}

e. Modules

Bicep supports modularization, allowing you to break down large templates into smaller, reusable components called modules.

Syntax:

xxxxxxxxxx
7
1
module moduleName 'path/to/module.bicep' = {
2
  name: 'moduleName'
3
  params: {
4
    param1: value
5
    param2: value
6
  }
7
}

Example:

xxxxxxxxxx
7
1
module myVNetModule './vnet.bicep' = {
2
  name: 'myVNetModule'
3
  params: {
4
    location: 'East US'
5
    vnetName: 'myVNet'
6
  }
7
}

f. Outputs

Outputs are values that you can retrieve after the deployment. These can be used to pass values to other templates or to display information about the deployment.

Syntax:

xxxxxxxxxx
1
1
output outputName outputType = value

Example:

xxxxxxxxxx
1
1
output vnetId string = vnet.id

4. Other Features in Bicep

a. Loops (For-Each)

Bicep allows you to iterate over collections of data, similar to loops in programming languages.

Syntax:

xxxxxxxxxx
1
1
[for item in collection: <expression>]

Example: Create multiple subnets in a VNet.

xxxxxxxxxx
20
1
param subnetNames array = ['subnet1', 'subnet2']
2
resource vnet 'Microsoft.Network/virtualNetworks@2020-05-01' = {
3
  name: 'myVNet'
4
  location: 'East US'
5
  properties: {
6
    addressSpace: {
7
      addressPrefixes: [
8
        '10.0.0.0/16'
9
      ]
10
    }
11
  }
12
}
13
// Loop over subnetNames to create multiple subnets
14
resource subnet 'Microsoft.Network/virtualNetworks/subnets@2020-05-01' = [for subnetName in subnetNames: {
15
  name: '${vnet.name}/${subnetName}'
16
  parent: vnet
17
  properties: {
18
    addressPrefix: '10.0.1.0/24'
19
  }
20
}]

b. Conditional Deployment (If Statements)

Bicep allows conditional resource deployment using if expressions.

Syntax:

xxxxxxxxxx
1
1
condition: <expression>

Example:

xxxxxxxxxx
12
1
param createVnet bool = true
2
resource vnet 'Microsoft.Network/virtualNetworks@2020-05-01' = if (createVnet) {
3
  name: 'myVNet'
4
  location: 'East US'
5
  properties: {
6
    addressSpace: {
7
      addressPrefixes: [
8
        '10.0.0.0/16'
9
      ]
10
    }
11
  }
12
}

c. Multiline Strings

You can use multiline strings to make your Bicep code more readable.

Syntax:

xxxxxxxxxx
5
1
var longString = '''
2
  This is a
3
  multiline string
4
  in Bicep.
5
'''

d. Referencing Existing Resources

You can reference existing resources in your Bicep file using the existing keyword.

Example:

xxxxxxxxxx
3
1
resource existingVnet 'Microsoft.Network/virtualNetworks@2020-05-01' existing = {
2
  name: 'existingVnetName'
3
}

Summary

Bicep provides a streamlined and flexible way to define Azure resources in a declarative manner. By understanding the core components (scope, parameters, variables, resources, modules, and outputs), along with advanced features like loops, conditionals, and referencing existing resources, you can effectively manage your Azure infrastructure as code.