bicep

Bicep is a declarative language for describing and deploying Azure resources

3,206

742

3,206

1,273

View on GitHub

Top Related Projects

terraform

42,146

Terraform enables you to safely and predictably create, change, and improve infrastructure. It is a source-available tool that codifies APIs into declarative configuration files that can be shared amongst team members, treated as code, edited, reviewed, and versioned.

pulumi

20,922

Pulumi - Infrastructure as Code in any programming language 🚀

aws-cdk

11,501

The AWS Cloud Development Kit is a framework for defining cloud infrastructure in code

kubernetes

109,710

Production-Grade Container Scheduling and Management

ansible

62,307

Ansible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com.

Quick Overview

Bicep is a domain-specific language (DSL) for deploying Azure resources declaratively. It aims to simplify the authoring experience with a cleaner syntax, improved type safety, and better support for modularity and code reuse compared to ARM templates.

Pros

Simpler and more concise syntax than ARM templates
Strong type safety and validation at authoring time
Improved modularity and code reuse capabilities
Seamless integration with existing Azure tooling and CI/CD pipelines

Cons

Limited to Azure resources only (not cross-cloud)
Relatively new, so the ecosystem and community support are still growing
Learning curve for those familiar with ARM templates or other IaC tools
Some advanced scenarios may still require ARM template snippets

Code Examples

Deploying a storage account:

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

Creating a virtual network with a subnet:

resource vnet 'Microsoft.Network/virtualNetworks@2021-03-01' = {
  name: 'myVNet'
  location: 'eastus'
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/16'
      ]
    }
    subnets: [
      {
        name: 'mySubnet'
        properties: {
          addressPrefix: '10.0.0.0/24'
        }
      }
    ]
  }
}

Using a module for reusability:

module appServicePlan 'modules/appServicePlan.bicep' = {
  name: 'appServicePlanDeploy'
  params: {
    name: 'myAppServicePlan'
    location: 'eastus'
    sku: 'S1'
  }
}

Getting Started

Install Bicep CLI:
```
az bicep install
```

Create a new Bicep file (e.g., main.bicep):

param location string = 'eastus'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: 'mystorageaccount'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

Deploy the Bicep file:

az deployment group create --resource-group myResourceGroup --template-file main.bicep

Competitor Comparisons

terraform

42,146

Pros of Terraform

Multi-cloud support, allowing infrastructure management across various providers
Larger ecosystem with extensive provider and module libraries
More mature and widely adopted in the industry

Cons of Terraform

Steeper learning curve, especially for those new to IaC
Requires manual state management and can be complex in large-scale deployments
Less native integration with Azure-specific features

Code Comparison

Terraform:

resource "azurerm_resource_group" "example" {
  name     = "example-resources"
  location = "West Europe"
}

Bicep:

resource resourceGroup 'Microsoft.Resources/resourceGroups@2021-04-01' = {
  name: 'example-resources'
  location: 'West Europe'
}

Both Terraform and Bicep are Infrastructure as Code (IaC) tools, but they have different focuses and strengths. Terraform is a multi-cloud solution with a larger ecosystem, while Bicep is specifically designed for Azure deployments. Terraform's HCL syntax is more verbose compared to Bicep's concise and Azure-native syntax. Bicep integrates more seamlessly with Azure services and provides better support for Azure-specific features. However, Terraform's broader adoption and multi-cloud capabilities make it a more versatile choice for organizations working with multiple cloud providers.

pulumi

20,922

Pulumi - Infrastructure as Code in any programming language 🚀

Pros of Pulumi

Multi-cloud support: Works with various cloud providers, not limited to Azure
Uses familiar programming languages (Python, JavaScript, etc.) for infrastructure definition
Offers more flexibility and advanced programming constructs

Cons of Pulumi

Steeper learning curve for those unfamiliar with programming languages
Potentially more complex setup and management compared to Bicep's simplicity
May require additional tooling and dependencies

Code Comparison

Bicep example:

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
}

Pulumi example (Python):

from pulumi_azure import storage

account = storage.Account("mystorageaccount",
    location="eastus",
    account_tier="Standard",
    account_replication_type="LRS")

Both examples create a storage account in Azure, but Pulumi uses Python syntax while Bicep uses its own domain-specific language. Pulumi's approach allows for more complex logic and reusability, while Bicep offers a more Azure-specific and potentially simpler syntax for Azure resources.

aws-cdk

11,501

The AWS Cloud Development Kit is a framework for defining cloud infrastructure in code

Pros of aws-cdk

Supports multiple programming languages (TypeScript, Python, Java, C#)
Offers a higher level of abstraction with constructs
Provides built-in testing capabilities

Cons of aws-cdk

Steeper learning curve due to its complexity
Requires compilation step before deployment
Less direct control over generated CloudFormation templates

Code Comparison

aws-cdk (TypeScript):

import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';

const bucket = new s3.Bucket(this, 'MyBucket', {
  versioned: true,
  encryption: s3.BucketEncryption.S3_MANAGED,
});

bicep:

resource myBucket 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: 'mybucketname'
  location: resourceGroup().location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

Both aws-cdk and bicep aim to simplify infrastructure-as-code, but they take different approaches. aws-cdk offers a more programmatic experience with support for multiple languages, while bicep provides a domain-specific language closer to Azure Resource Manager templates. The choice between them often depends on the cloud provider and personal preference for syntax and abstraction level.

kubernetes

109,710

Production-Grade Container Scheduling and Management

Pros of Kubernetes

Widely adopted, mature, and vendor-neutral container orchestration platform
Extensive ecosystem with a large community and numerous third-party tools
Supports multi-cloud and hybrid cloud deployments

Cons of Kubernetes

Steeper learning curve and more complex setup compared to Bicep
Requires more resources and overhead for small-scale deployments
Less tightly integrated with Azure-specific services and features

Code Comparison

Bicep (Infrastructure as Code for Azure):

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
}

Kubernetes (Container Orchestration):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx

ansible

62,307

Pros of Ansible

Multi-platform support for various cloud providers and on-premises infrastructure
Agentless architecture, requiring only SSH access to managed nodes
Extensive community-driven module ecosystem

Cons of Ansible

Steeper learning curve, especially for complex playbooks
Performance can be slower for large-scale deployments
Less tightly integrated with Azure-specific features

Code Comparison

Ansible playbook example:

- name: Create Azure VM
  hosts: localhost
  tasks:
    - name: Create resource group
      azure_rm_resourcegroup:
        name: myResourceGroup
        location: eastus
    - name: Create virtual machine
      azure_rm_virtualmachine:
        resource_group: myResourceGroup
        name: myVM
        vm_size: Standard_DS1_v2

Bicep template example:

resource virtualMachine 'Microsoft.Compute/virtualMachines@2021-03-01' = {
  name: 'myVM'
  location: 'eastus'
  properties: {
    hardwareProfile: {
      vmSize: 'Standard_DS1_v2'
    }
  }
}

The Ansible playbook is more verbose but offers a task-based approach, while the Bicep template is more concise and declarative, focusing specifically on Azure resources.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Azure Bicep

For all you need to know about the Bicep language, check out our Bicep documentation.

What is Bicep?

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 (Note: even if Bicep warns that type information is not available for a resource, it can still be deployed).

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

Goals

Build the best possible language for describing, validating, and deploying infrastructure to Azure.
The language should provide a transparent abstraction for the underlying platform. There must be no "onboarding step" to enable Bicep support for a new resource type and/or api version.
Code should be easy to understand at a glance and straightforward to learn, regardless of your experience with other programming languages.
Users should be given a lot of freedom to modularize and re-use their code. Code re-use should not require any 'copy/paste'-ing.
Tooling should provide a high level of resource discoverability and validation, and should be developed alongside the compiler rather than added at the end.
Users should have a high level of confidence that their code is 'syntactically valid' before deploying.

Non-goals

Build a general purpose language to meet any need. This will not replace general purpose languages and you may still need to do pre or post-Bicep execution tasks in a script or high-level programming language.
Provide a first-class provider model for non-Azure related tasks. While we will likely introduce an extensibility model at some point, any extension points are intended to be focused on Azure infra or application deployment related tasks.

Get started with Bicep

To get going with Bicep:

Start by installing the tooling.
Complete the Bicep Learning Path

Alternatively, you can use the VS Code Devcontainer/Codespaces repo to get a preconfigured environment.

If you have an existing ARM Template or set of resources that you would like to convert to .bicep format, see Decompiling an ARM Template.

Also, there is a rich library of examples in the azure-quickstart-templates repo to help you get started.

How does Bicep work?

First, author your Bicep code using the Bicep language service as part of the Bicep VS Code extension

Both Az CLI (2.20.0+) and the PowerShell Az module (v5.6.0+) have Bicep support built-in. This means you can use the standard deployment commands with your *.bicep files and the tooling will transpile the code and send it to ARM on your behalf. For example, to deploy main.bicep to a resource group my-rg, we can use the CLI command we are already used to:

az deployment group create -f ./main.bicep -g my-rg

For more detail on taking advantage of new Bicep constructs that replace an equivalent from ARM Templates, you can read the moving from ARM => Bicep doc.

Known limitations

Bicep is newline sensitive. We are exploring ways we can remove/relax this restriction (#146)
No support for the concept of apiProfile which is used to map a single apiProfile to a set apiVersion for each resource type. We are looking to bring support for this type of capability, but suspect it will work slightly differently. Discussion is in #622

FAQ

What unique benefits do you get with Bicep?

Day 0 resource provider support. Any Azure resource â whether in private or public preview or GA â can be provisioned using Bicep.
Much simpler syntax compared to equivalent ARM Template JSON
No state or state files to manage. All state is stored in Azure, so makes it easy to collaborate and make changes to resources confidently.
Tooling is the cornerstone to any great experience with a programming language. Our VS Code extension for Bicep makes it extremely easy to author and get started with advanced type validation based on all Azure resource type API definitions.
Easily break apart your code with native modules
Supported by Microsoft support and 100% free to use.

Why create a new language instead of using an existing one?

Bicep is more of a revision to the existing ARM template language rather than an entirely new language. While most of the syntax has been changed, the core functionality of ARM templates and the runtime remains the same. You have the same template functions, same resource declarations, etc. Part of the complexity with ARM Templates is due to the "DSL" being embedded inside of JSON. With Bicep, we are revising the syntax of this DSL and moving it into its own .bicep file format. Before going down this path, we closely evaluated using an existing high-level programming language, but ultimately determined that Bicep would be easier to learn for our target audience. We are open to other implementations of Bicep in other languages.

We spent a lot of time researching various different options and even prototyped a TypeScript based approach. We did over 120 customer calls, Microsoft Most Valuable Professional (MVP) conversations and collected quantitative data. We learned that in majority of organizations, it was the cloud enablement teams that were responsible for provisioning the Azure infra. These folks were not familiar with programming languages and did not like that approach as it had a steep learning curve. These users were our target users. In addition, authoring ARM template code in a higher level programming language would require you to reconcile two uneven runtimes, which ends up being confusing to manage. At the end of the day, we simply want customers to be successful on Azure. In the future if we hear more feedback asking us to support a programming language approach, we are open to that as well. If you'd like to use a high-level programming language to deploy Azure Infra we recommend Farmer, the Terraform CDK or Pulumi.

Why not focus your energy on Terraform or other third-party IaC offerings?

Using Terraform can be a great choice depending on the requirements of the organization, and if you are happy using Terraform there is no reason to switch. At Microsoft, we have teams actively investing to make sure the Terraform on Azure experience is the best it can be.

That being said, there is a huge customer base using ARM templates today because it provides a unique set of capabilities and benefits. We wanted to make the experience for those customers first-class as well, in addition to making it easier to start for Azure focused customers who have not yet transitioned to infra-as-code.

Fundamentally, we believe that configuration languages and tools are always going to be polyglot and different users will prefer different tools for different situations. We want to make sure all of these tools are great on Azure, Bicep is only a part of that effort.

Is this ready for production use?

Yes. 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.

Is this only for Azure?

Bicep is a DSL focused on deploying end-to-end solutions in Azure. In practice, that usually means working with some non-Azure APIs (i.e. creating Kubernetes deployments or users in a database), so we expect to provide some extensibility points. That being said, currently only Azure resources exposed through the ARM API can be created with Bicep.

What happens to my existing ARM Template investments?

One of our goals is to make the transition from ARM Templates to Bicep as easy as possible. The Bicep CLI supports a decompile command to generate Bicep code from an ARM template. Please see Decompiling an ARM Template for usage information.

Note that while we want to make it easy to transition to Bicep, we will continue to support and enhance the underlying ARM Template JSON language. As mentioned in What is Bicep?, ARM Template JSON remains the wire format that will be sent to Azure to carry out a deployment.

Get Help, Report an issue

We are here to help you be successful with Bicep, please do not hesitate to reach out to us.

If you need help or have a generic question such as âwhere can I find an example forâ¦â or âI need help converting my ARM Template to Bicepâ you can open a discussion
If you have a bug to report or a new feature request for Bicep please open an issue

Reference

Community Bicep projects

Alternatives

Because we are now treating the ARM Template as an IL, we expect and encourage other implementations of IL (ARM Template) generation. We'll keep a running list of alternatives for creating ARM templates that may better fit your use case.

Farmer (@isaacabraham) - Generate and deploy ARM Templates on .NET
Cloud Maker (@cloud-maker-ai) - Draw deployable infrastructure diagrams that are converted to ARM templates or Bicep

Telemetry

When using the Bicep VS Code extension, VS Code collects usage data and sends it to Microsoft to help improve our products and services. Read our privacy statement to learn more. If you donât wish to send usage data to Microsoft, you can set the telemetry.enableTelemetry setting to false. Learn more in our FAQ.

License

All files except for the Azure Architecture SVG Icons in the repository are subject to the MIT license.

The Azure Architecture SVG Icons used in the Bicep VS Code extension are subject to the Terms of Use.

Contributing

See Contributing to Bicep for information on building/running the code, contributing code, contributing examples and contributing feature requests or bug reports.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot