Using Locally with Bicep

Preview

During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in

Using Locally with Bicep

Bicep files describe the Azure infrastructure you want to deploy, and compile down to ARM Templates. You can either use the locally deploy command which simplifies the Bicep deployment (by generating a resource group/deployment name, if unspecified, and deploys into the first subscription alphabetically by default) - but you can also perform the deployment using the Azure CLI (and you can find this below). Using locally deploy requires Bicep to be installed.

Every Bicep template targets a scope - a Resource Group (the default), a Subscription, a Management Group or a Tenant.

Resource Group Deployments

Most templates deploy into a Resource Group. For example, this template creates an Availability Set:

resource availabilitySet 'Microsoft.Compute/availabilitySets@2024-11-01' = {
  name: 'example-using-bicep'
  location: 'berlin'
  properties: {
    platformFaultDomainCount: 3
    platformUpdateDomainCount: 5
  }
  sku: {
    name: 'Aligned'
  }
}

If Locally isn't already running, we'll need to start it by running:

$ locally build

Then, if the template's saved as template.bicep, you can deploy it with:

$ locally deploy template.bicep

If you don't specify a Subscription, the first Subscription alphabetically will be used, and if you don't specify a name for the Resource Group or Deployment then one will be randomly generated as needed. You can specify these values by setting:

  • --subscription {UUID} - the Subscription to deploy into. Defaults to the First Subscription.
  • --resource-group {name} - the Resource Group to deploy into, which is created if it doesn't already exist.
  • --deployment {name} - the name to record the Deployment under.
  • --parameters {file} - a parameters file, either .bicepparam or .json.

For example, to deploy into a Resource Group named dev in a specific Subscription:

$ locally deploy --subscription 9fae9a7d-5fd4-4b18-8efc-22ac8eb6eaaa --resource-group dev template.bicep

Subscription Deployments

To deploy at the Subscription scope instead, declare targetScope = 'subscription' at the top of the template. This one creates a Resource Group:

targetScope = 'subscription'

resource resourceGroup 'Microsoft.Resources/resourceGroups@2021-04-01' = {
  name: 'from-subscription-deployment'
  location: 'berlin'
}

Subscription deployments also take a --location flag, which sets where the Deployment's metadata is stored and defaults to berlin:

$ locally deploy --location berlin subscription-template.bicep

The --subscription, --deployment and --parameters flags work the same way as for Resource Group deployments, but --resource-group doesn't apply at this scope.

Management Group Deployments

Available on Starter Standard Team Compare plans →

To deploy at a Management Group, set targetScope to 'managementGroup'. This one adds a Policy Definition to the Management Group, which every Subscription beneath it can then assign:

targetScope = 'managementGroup'

resource requireEnvironmentTag 'Microsoft.Authorization/policyDefinitions@2021-06-01' = {
  name: 'require-environment-tag'
  properties: {
    displayName: 'Require an environment tag on Resource Groups'
    policyType: 'Custom'
    mode: 'All'
    policyRule: {
      if: {
        allOf: [
          { field: 'type', equals: 'Microsoft.Resources/subscriptions/resourceGroups' }
          { field: 'tags[\'environment\']', exists: 'false' }
        ]
      }
      then: { effect: 'deny' }
    }
  }
}

Pass the Management Group to deploy into with --management-group:

$ locally deploy --management-group platform management-group.bicep

The --deployment, --location and --parameters flags work the same way as for Subscription deployments.

Heads up

This feature is under active development and may contain bugs or incomplete functionality.

Tenant Deployments

Locally doesn't support Tenant scoped deployments at this time, but we plan to in the future. We're tracking this feature request in this issue on the Locally Issue tracker.

Deploying via the Azure CLI

If you'd rather use the Azure CLI, prefix az deployment group create with locally run to deploy a Bicep template into an existing Resource Group:

$ locally run az deployment group create --resource-group example --template-file template.bicep

And az deployment mg create deploys into a Management Group:

$ locally run az deployment mg create --management-group-id platform --location berlin --template-file management-group.bicep

Next steps

You can see what you've deployed in the Locally Dashboard, and the Examples include Bicep templates for many common resources. If you're writing JSON templates instead, see the ARM Templates guide.

Each deployment has its own page in the Dashboard, showing each resource as it's provisioned - and you can cancel a deployment from there while it's running.

Preview

During Public Preview you can use the Team plan for free, and get an early-adopter discount at GA. Sign in

A local cloud for you and your AI agents.

Your Azure infrastructure, running on your machine. Deploy in seconds, break things freely, and ship to Azure when you're ready.