Bicep Deployment Methods

Writing a Bicep file is only half the work. Deploying it to Azure is the other half. Bicep templates deploy through multiple methods — Azure CLI, Azure PowerShell, Azure Portal, and CI/CD pipelines. Each method suits a different workflow. Understanding all of them helps pick the right tool for each situation.

Think of deployment methods like ways to send a package. The same package ships by courier, post office, or hand delivery. Each route delivers the same item to the same destination — the difference is speed, convenience, and level of control.

Deployment Scopes – Where Resources Land

Before exploring deployment commands, understand where Bicep files deploy. Azure has four deployment scopes and each requires a different command.

Azure Deployment Scopes

Tenant
  │
  ├── Management Group  ──► az deployment mg create
  │
  └── Subscription      ──► az deployment sub create
       │
       └── Resource Group  ──► az deployment group create  (most common)
            │
            └── Resources (VM, Storage, SQL, etc.)

Scope	Azure CLI Command	When to Use
Resource Group	az deployment group create	Most resource deployments
Subscription	az deployment sub create	Creating resource groups, policies
Management Group	az deployment mg create	Organization-wide policies
Tenant	az deployment tenant create	Root-level management groups

Method 1 – Azure CLI Deployment

Azure CLI is the most common deployment method for engineers working from a terminal. The core command for resource group deployments is az deployment group create.

Basic Deployment Command

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

Deployment with Inline Parameters

az deployment group create \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --parameters location=westus environment=prod appName=mywebapp

Deployment with a Parameter File

az deployment group create \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --parameters prod.bicepparam

Named Deployment

az deployment group create \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --name release-2024-v1 \
  --parameters prod.bicepparam

Naming a deployment makes it easy to find in the Azure Portal under Deployments. If no name is given, Azure uses the template file name by default.

What-If – Preview Before Deploying

The --what-if flag shows exactly what Azure will create, modify, or delete — without actually doing anything. Always run what-if before deploying to production.

az deployment group create \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --parameters prod.bicepparam \
  --what-if

Sample What-If Output

Resource and property changes are indicated with these symbols:
  + Create
  ~ Modify
  - Delete
  x Ignore
  = Nochange

The deployment will make the following changes:

Scope: /subscriptions/.../resourceGroups/myResourceGroup

  + Microsoft.Storage/storageAccounts/mystorage001
      apiVersion: "2023-01-01"
      id:         "/subscriptions/.../storageAccounts/mystorage001"
      location:   "eastus"
      name:       "mystorage001"
      sku.name:   "Standard_LRS"
      kind:       "StorageV2"

Subscription-Level Deployment

// Set targetScope = 'subscription' in the Bicep file first

az deployment sub create \
  --location eastus \
  --template-file main.bicep \
  --parameters main.bicepparam

Subscription-level deployments require --location instead of --resource-group because the deployment itself is not inside a resource group.

Method 2 – Azure PowerShell Deployment

Azure PowerShell is the preferred tool in Windows-heavy or enterprise environments. The commands mirror Azure CLI functionality with PowerShell syntax.

Resource Group Deployment

New-AzResourceGroupDeployment `
  -ResourceGroupName myResourceGroup `
  -TemplateFile main.bicep `
  -location eastus `
  -environment prod

With Parameter File

New-AzResourceGroupDeployment `
  -ResourceGroupName myResourceGroup `
  -TemplateFile main.bicep `
  -TemplateParameterFile prod.bicepparam

What-If with PowerShell

New-AzResourceGroupDeployment `
  -ResourceGroupName myResourceGroup `
  -TemplateFile main.bicep `
  -WhatIf

Method 3 – Azure Portal Deployment

The Azure Portal provides a graphical way to deploy Bicep files. This method suits teams new to Bicep or one-off deployments that do not need scripting.

Portal Deployment Steps

Step 1: Go to Azure Portal → search "Deploy a custom template"
          │
          ▼
Step 2: Click "Build your own template in the editor"
          │
          ▼
Step 3: Paste the Bicep content or upload the file
          │
          ▼
Step 4: Click Save → Fill in parameters in the form
          │
          ▼
Step 5: Click "Review + create" → then "Create"
          │
          ▼
Step 6: Watch deployment progress in real time

Deployment Modes – Incremental vs Complete

Bicep deployments run in one of two modes. Understanding the difference prevents accidental resource deletion.

+-------------------------------------------------------------+
|             Deployment Modes Comparison                     |
+-----------------+-------------------------------------------+
|  Mode           |  Behavior                                 |
+-----------------+-------------------------------------------+
|  Incremental    |  Adds or updates resources in the Bicep   |
|  (Default)      |  file. Leaves existing resources alone.   |
+-----------------+-------------------------------------------+
|  Complete       |  Adds or updates resources in the Bicep   |
|                 |  file. DELETES any resource in the        |
|                 |  resource group NOT in the Bicep file.    |
+-----------------+-------------------------------------------+

Incremental Mode Example

Resource Group Before:  VM, Storage, Old-App
Bicep File Contains:    VM, Storage, New-App

After Incremental Deployment:
→ VM: unchanged
→ Storage: unchanged
→ Old-App: STILL EXISTS (not touched)
→ New-App: CREATED

Complete Mode Example

Resource Group Before:  VM, Storage, Old-App
Bicep File Contains:    VM, Storage, New-App

After Complete Deployment:
→ VM: unchanged
→ Storage: unchanged
→ Old-App: DELETED (not in Bicep file)
→ New-App: CREATED

Setting Deployment Mode

# Incremental (default – safe)
az deployment group create \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --mode Incremental

# Complete (destructive – use with caution)
az deployment group create \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --mode Complete

Checking Deployment Status

List All Deployments in a Resource Group

az deployment group list \
  --resource-group myResourceGroup \
  --output table

Show a Specific Deployment

az deployment group show \
  --resource-group myResourceGroup \
  --name release-2024-v1

Get Outputs from a Completed Deployment

az deployment group show \
  --resource-group myResourceGroup \
  --name release-2024-v1 \
  --query "properties.outputs" \
  --output json

List Deployment Operations (useful for debugging failures)

az deployment group operation list \
  --resource-group myResourceGroup \
  --name release-2024-v1 \
  --output table

Deployment Validation – Catch Errors Before They Happen

Validate a Bicep file without deploying it. Validation checks for syntax errors, missing parameters, and policy violations.

az deployment group validate \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --parameters prod.bicepparam

A successful validation returns a JSON object with "provisioningState": "Succeeded". A failed validation shows the exact error that would occur during deployment.

Deployment with az Stack – Managing Deployment Stacks

Deployment Stacks are a newer Azure feature that tracks all resources deployed by a Bicep file as a single managed unit. Deleting the stack deletes all its resources, making cleanup simple.

# Create or update a deployment stack
az stack group create \
  --name myAppStack \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --parameters prod.bicepparam \
  --deny-settings-mode none

# Delete the stack and all its resources
az stack group delete \
  --name myAppStack \
  --resource-group myResourceGroup \
  --yes

Common Deployment Errors and Solutions

Error	Cause	Solution
ResourceGroupNotFound	Resource group does not exist	Run az group create first
InvalidTemplateDeployment	Bicep file has a syntax or logic error	Run az bicep build to check for errors
AccountNameInvalid	Resource name violates naming rules	Check the name length and allowed characters
StorageAccountAlreadyTaken	Storage account name is globally taken	Use uniqueString() to generate a unique suffix
AuthorizationFailed	Service principal lacks permissions	Assign the Contributor role to the deploying identity
QuotaExceeded	Subscription limit reached for resource type	Request a quota increase or use a different region

Deployment Workflow – From Code to Cloud

Complete Deployment Workflow

Write Bicep File
      │
      ▼
az bicep build (optional – check for compilation errors)
      │
      ▼
az deployment group validate (check for Azure-level errors)
      │
      ▼
az deployment group create --what-if (preview changes)
      │
      ▼
az deployment group create (deploy to Azure)
      │
      ▼
az deployment group show (verify outputs and status)

Summary

Bicep templates deploy through Azure CLI, Azure PowerShell, and the Azure Portal. The most common command is az deployment group create for resource group deployments. Subscription-level and management group deployments use different commands and require the matching targetScope in the Bicep file. Incremental mode is the safe default — complete mode deletes unmanaged resources. Always run --what-if before production deployments. Validation and what-if together prevent most deployment failures before they happen.

Previous lessons

Back to courses

Next lessons