Azure Deployment Preflight

Azure Deployment Preflight Validation

This skill validates Bicep deployments before execution, supporting both Azure CLI (az) and Azure Developer CLI (azd) workflows.

When to Use This Skill

• Before deploying infrastructure to Azure
• When preparing or reviewing Bicep files
• To preview what changes a deployment will make
• To verify permissions are sufficient for deployment
• Before running azd up, azd provision, or az deployment commands

Validation Process

Follow these steps in order. Continue to the next step even if a previous step fails—capture all issues in the final report.

Step 1: Detect Project Type

Determine the deployment workflow by checking for project indicators:

1. Check for azd project: Look for azure.yaml in the project root

• If found → Use azd workflow
• If not found → Use az CLI workflow

2. Locate Bicep files: Find all .bicep files to validate

• For azd projects: Check infra/ directory first, then project root
• For standalone: Use the file specified by the user or search common locations (infra/, deploy/, project root)

3. Auto-detect parameter files: For each Bicep file, look for matching parameter files:

• <filename>.bicepparam (Bicep parameters - preferred)
• <filename>.parameters.json (JSON parameters)
• parameters.json or parameters/<env>.json in same directory

Step 2: Validate Bicep Syntax

Run Bicep CLI to check template syntax before attempting deployment validation:

bicep build <bicep-file> --stdout

What to capture:

• Syntax errors with line/column numbers
• Warning messages
• Build success/failure status

If Bicep CLI is not installed:

• Note the issue in the report
• Continue to Step 3 (Azure will validate syntax during what-if)

Step 3: Run Preflight Validation

Choose the appropriate validation based on project type detected in Step 1.

For azd Projects (azure.yaml exists)

Use azd provision --preview to validate the deployment:

azd provision --preview

If an environment is specified or multiple environments exist:

azd provision --preview --environment <env-name>

For Standalone Bicep (no azure.yaml)

Determine the deployment scope from the Bicep file's targetScope declaration:

Run with Provider validation level first:

# Resource Group scope (most common)
az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Subscription scope
az deployment sub what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Management Group scope
az deployment mg what-if \
  --location <location> \
  --management-group-id <mg-id> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

# Tenant scope
az deployment tenant what-if \
  --location <location> \
  --template-file <bicep-file> \
  --parameters <param-file> \
  --validation-level Provider

Fallback Strategy:

If --validation-level Provider fails with permission errors (RBAC), retry with ProviderNoRbac:

az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  --validation-level ProviderNoRbac

Note the fallback in the report—the user may lack full deployment permissions.

Step 4: Capture What-If Results

Parse the what-if output to categorize resource changes:

For modified resources, capture the specific property changes.

Step 5: Generate Report

Create a Markdown report file in the project root named:

• preflight-report.md

Use the template structure from references/REPORT-TEMPLATE.md.

Report sections: 1. Summary - Overall status, timestamp, files validated, target scope 2. Tools Executed - Commands run, versions, validation levels used 3. Issues - All errors and warnings with severity and remediation 4. What-If Results - Resources to create/modify/delete/unchanged 5. Recommendations - Actionable next steps

Required Information

Before running validation, gather:

If required information is missing, prompt the user before proceeding.

Error Handling

See references/ERROR-HANDLING.md for detailed error handling guidance.

Key principle: Continue validation even when errors occur. Capture all issues in the final report.

Tool Requirements

This skill uses the following tools:

• Azure CLI (az) - Version 2.76.0+ recommended for --validation-level
• Azure Developer CLI (azd) - For projects with azure.yaml
• Bicep CLI (bicep) - For syntax validation
• Azure MCP Tools - For documentation lookups and best practices

Check tool availability before starting:

az --version
azd version
bicep --version

Example Workflow

1. User: "Validate my Bicep deployment before I run it" 2. Agent detects azure.yaml → azd project 3. Agent finds infra/main.bicep and infra/main.bicepparam 4. Agent runs bicep build infra/main.bicep --stdout 5. Agent runs azd provision --preview 6. Agent generates preflight-report.md in project root 7. Agent summarizes findings to user

Reference Documentation

• Validation Commands Reference
• Report Template
• Error Handling Guide

Error Handling Guide

This reference documents common errors during preflight validation and how to handle them.

Core Principle

Continue on failure. Capture all issues in the final report rather than stopping at the first error. This gives users a complete picture of what needs to be fixed.

---

Authentication Errors

Not Logged In (Azure CLI)

Detection:

ERROR: Please run 'az login' to setup account.
ERROR: AADSTS700082: The refresh token has expired

Exit Codes: Non-zero

Handling: 1. Note the error in the report 2. Include remediation steps 3. Skip remaining Azure CLI commands 4. Continue with other validation steps if possible

Report Entry:

#### ❌ Azure CLI Authentication Required

- **Severity:** Error
- **Source:** az cli
- **Message:** Not logged in to Azure CLI
- **Remediation:** Run `az login` to authenticate, then re-run preflight validation
- **Documentation:** https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli

Not Logged In (azd)

Detection:

ERROR: not logged in, run `azd auth login` to login

Handling: 1. Note the error in the report 2. Skip azd commands 3. Suggest azd auth login

Report Entry:

#### ❌ Azure Developer CLI Authentication Required

- **Severity:** Error
- **Source:** azd
- **Message:** Not logged in to Azure Developer CLI
- **Remediation:** Run `azd auth login` to authenticate, then re-run preflight validation

Token Expired

Detection:

AADSTS700024: Client assertion is not within its valid time range
AADSTS50173: The provided grant has expired

Handling: 1. Note the error 2. Suggest re-authentication 3. Skip Azure operations

---

Permission Errors

Insufficient RBAC Permissions

Detection:

AuthorizationFailed: The client '...' with object id '...' does not have authorization 
to perform action '...' over scope '...'

Handling: 1. First attempt: Retry with --validation-level ProviderNoRbac 2. Note the permission limitation in the report 3. If ProviderNoRbac also fails, report the specific missing permission

Report Entry:

#### ⚠️ Limited Permission Validation

- **Severity:** Warning
- **Source:** what-if
- **Message:** Full RBAC validation failed; using read-only validation
- **Detail:** Missing permission: `Microsoft.Resources/deployments/write` on scope `/subscriptions/xxx`
- **Recommendation:** Request Contributor role on the target resource group, or verify deployment permissions with your administrator

Resource Group Not Found

Detection:

ResourceGroupNotFound: Resource group 'xxx' could not be found.

Handling: 1. Note in report 2. Suggest creating the resource group 3. Skip what-if for this scope

Report Entry:

#### ❌ Resource Group Does Not Exist

- **Severity:** Error
- **Source:** what-if
- **Message:** Resource group 'my-rg' does not exist
- **Remediation:** Create the resource group before deployment:

az group create --name my-rg --location eastus

Subscription Access Denied

Detection:

SubscriptionNotFound: The subscription 'xxx' could not be found.
InvalidSubscriptionId: Subscription '...' is not valid

Handling: 1. Note in report 2. Suggest checking subscription ID 3. List available subscriptions

---

Bicep Syntax Errors

Compilation Errors

Detection:

/path/main.bicep(22,51) : Error BCP064: Found unexpected tokens
/path/main.bicep(10,5) : Error BCP018: Expected the "=" character at this location

Handling: 1. Parse error output for line/column numbers 2. Include all errors in report (don't stop at first) 3. Continue to what-if (may provide additional context)

Report Entry:

#### ❌ Bicep Syntax Error

- **Severity:** Error
- **Source:** bicep build
- **Location:** `main.bicep:22:51`
- **Code:** BCP064
- **Message:** Found unexpected tokens in interpolated expression
- **Remediation:** Check the string interpolation syntax at line 22
- **Documentation:** https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/diagnostics/bcp064

Module Not Found

Detection:

Error BCP091: An error occurred reading file. Could not find file '...'
Error BCP190: The module is not valid

Handling: 1. Note missing module 2. Check if bicep restore is needed 3. Verify module path

Parameter File Issues

Detection:

Error BCP032: The value must be a compile-time constant
Error BCP035: The specified object is missing required properties

Handling: 1. Note parameter issues 2. Indicate which parameters are problematic 3. Suggest fixes

---

Tool Not Installed

Azure CLI Not Found

Detection:

'az' is not recognized as an internal or external command
az: command not found

Handling: 1. Note in report 2. Provide installation instructions.

• If available use the Azure MCP extension_cli_install tool to get installation instructions.
• Otherwise look for instructions at https://learn.microsoft.com/en-us/cli/azure/install-azure-cli.

3. Skip az commands

Report Entry:

#### ⏭️ Azure CLI Not Installed

- **Severity:** Warning
- **Source:** environment
- **Message:** Azure CLI (az) is not installed or not in PATH
- **Remediation:** Install the Azure CLI <ADD INSTALLATION INSTRUCTIONS HERE>
- **Impact:** What-if validation using az commands was skipped

Bicep CLI Not Found

Detection:

'bicep' is not recognized as an internal or external command
bicep: command not found

Handling: 1. Note in report 2. Azure CLI may have built-in Bicep - try az bicep build 3. Provide installation link

Report Entry:

#### ⏭️ Bicep CLI Not Installed

- **Severity:** Warning
- **Source:** environment
- **Message:** Bicep CLI is not installed
- **Remediation:** Install Bicep CLI: https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install
- **Impact:** Syntax validation was skipped; Azure will validate during what-if

Azure Developer CLI Not Found

Detection:

'azd' is not recognized as an internal or external command
azd: command not found

Handling: 1. If azure.yaml exists, this is required 2. Fall back to az CLI commands if possible 3. Note in report

---

What-If Specific Errors

Nested Template Limits

Detection:

The deployment exceeded the nested template limit of 500

Handling: 1. Note as warning (not error) 2. Explain affected resources show as "Ignore" 3. Suggest manual review

Template Link Not Supported

Detection:

templateLink references in nested deployments won't be visible in what-if

Handling: 1. Note as warning 2. Explain limitation 3. Resources will be verified during actual deployment

Unevaluated Expressions

Detection: Properties showing function names like [utcNow()] instead of values

Handling: 1. Note as informational 2. Explain these are evaluated at deployment time 3. Not an error

---

Network Errors

Timeout

Detection:

Connection timed out
Request timed out

Handling: 1. Suggest retry 2. Check network connectivity 3. May indicate Azure service issues

SSL/TLS Errors

Detection:

SSL: CERTIFICATE_VERIFY_FAILED
unable to get local issuer certificate

Handling: 1. Note in report 2. May indicate proxy or corporate firewall 3. Suggest checking SSL settings

---

Fallback Strategy

When primary validation fails, attempt fallbacks in order:

Provider (full RBAC validation)
    ↓ fails with permission error
ProviderNoRbac (validation without write permission check)
    ↓ fails
Template (static syntax only)
    ↓ fails
Report all failures and skip what-if analysis

Always continue to generate the report, even if all validation steps fail.

---

Error Report Aggregation

When multiple errors occur, aggregate them logically:

1. Group by source (bicep, what-if, permissions) 2. Order by severity (errors before warnings) 3. Deduplicate similar errors 4. Provide summary count at the top

Example:

## Issues

Found **3 errors** and **2 warnings**

### Errors (3)

1. [Bicep Syntax Error - main.bicep:22:51](#error-1)
2. [Bicep Syntax Error - main.bicep:45:10](#error-2)
3. [Resource Group Not Found](#error-3)

### Warnings (2)

1. [Limited Permission Validation](#warning-1)
2. [Nested Template Limit Reached](#warning-2)

---

Exit Code Reference

Preflight Report Template

Use this template structure when generating preflight-report.md in the project root.

---

Template

# Azure Deployment Preflight Report

**Generated:** {timestamp}
**Status:** {overall-status}

---

## Summary

| Property | Value |
|----------|-------|
| **Template File(s)** | {bicep-files} |
| **Parameter File(s)** | {param-files-or-none} |
| **Project Type** | {azd-project | standalone-bicep} |
| **Deployment Scope** | {resourceGroup | subscription | managementGroup | tenant} |
| **Target** | {resource-group-name | subscription-name | mg-id} |
| **Validation Level** | {Provider | ProviderNoRbac} |

### Validation Results

| Check | Status | Details |
|-------|--------|---------|
| Bicep Syntax | {✅ Pass | ❌ Fail | ⚠️ Warnings | ⏭️ Skipped} | {details} |
| What-If Analysis | {✅ Pass | ❌ Fail | ⏭️ Skipped} | {details} |
| Permission Check | {✅ Pass | ⚠️ Limited | ❌ Fail} | {details} |

---

## Tools Executed

### Commands Run

| Step | Command | Exit Code | Duration |
|------|---------|-----------|----------|
| 1 | `{command}` | {0 | non-zero} | {duration} |
| 2 | `{command}` | {0 | non-zero} | {duration} |

### Tool Versions

| Tool | Version |
|------|---------|
| Azure CLI | {version} |
| Bicep CLI | {version} |
| Azure Developer CLI | {version-or-n/a} |

---

## Issues

{if-no-issues}
✅ **No issues found.** The deployment is ready to proceed.
{end-if}

{if-issues-exist}
### Errors

{for-each-error}
#### ❌ {error-title}

- **Severity:** Error
- **Source:** {bicep-build | what-if | permissions}
- **Location:** {file-path}:{line}:{column} (if applicable)
- **Message:** {error-message}
- **Remediation:** {suggested-fix}
- **Documentation:** {link-if-available}

{end-for-each}

### Warnings

{for-each-warning}
#### ⚠️ {warning-title}

- **Severity:** Warning
- **Source:** {source}
- **Message:** {warning-message}
- **Recommendation:** {suggested-action}

{end-for-each}
{end-if}

---

## What-If Results

{if-what-if-succeeded}

### Change Summary

| Change Type | Count |
|-------------|-------|
| 🆕 Create | {count} |
| 📝 Modify | {count} |
| 🗑️ Delete | {count} |
| ✓ No Change | {count} |
| ⚠️ Ignore | {count} |

### Resources to Create

{if-resources-to-create}
| Resource Type | Resource Name |
|---------------|---------------|
| {type} | {name} |
{end-if}

{if-no-resources-to-create}
*No resources will be created.*
{end-if}

### Resources to Modify

{if-resources-to-modify}
#### {resource-type}/{resource-name}

| Property | Current Value | New Value |
|----------|---------------|-----------|
| {property-path} | {current} | {new} |

{end-if}

{if-no-resources-to-modify}
*No resources will be modified.*
{end-if}

### Resources to Delete

{if-resources-to-delete}
| Resource Type | Resource Name |
|---------------|---------------|
| {type} | {name} |

> ⚠️ **Warning:** Resources listed for deletion will be permanently removed.
{end-if}

{if-no-resources-to-delete}
*No resources will be deleted.*
{end-if}

{end-if-what-if-succeeded}

{if-what-if-failed}
### What-If Analysis Failed

The what-if operation could not complete. See the Issues section for details.
{end-if}

---

## Recommendations

{generate-based-on-findings}

1. {recommendation-1}
2. {recommendation-2}
3. {recommendation-3}

---

## Next Steps

{if-all-passed}
The preflight validation passed. You can proceed with deployment:

**For azd projects:**

azd provision

or

azd up

**For standalone Bicep:**

az deployment group create \ --resource-group {rg-name} \ --template-file {bicep-file} \ --parameters {param-file}

{end-if}

{if-issues-exist}
Please resolve the issues listed above before deploying. After fixes:

1. Re-run preflight validation to verify fixes
2. Proceed with deployment once all checks pass
{end-if}

---

*Report generated by Azure Deployment Preflight Skill*

---

Status Values

Overall Status

Individual Check Status

---

Example Report

# Azure Deployment Preflight Report

**Generated:** 2026-01-16T14:32:00Z
**Status:** ⚠️ Pass with Warnings

---

## Summary

| Property | Value |
|----------|-------|
| **Template File(s)** | `infra/main.bicep` |
| **Parameter File(s)** | `infra/main.bicepparam` |
| **Project Type** | azd project |
| **Deployment Scope** | subscription |
| **Target** | my-subscription |
| **Validation Level** | Provider |

### Validation Results

| Check | Status | Details |
|-------|--------|---------|
| Bicep Syntax | ✅ Pass | No errors found |
| What-If Analysis | ⚠️ Warnings | 1 resource ignored due to nested template limits |
| Permission Check | ✅ Pass | Full deployment permissions verified |

---

## Tools Executed

### Commands Run

| Step | Command | Exit Code | Duration |
|------|---------|-----------|----------|
| 1 | `bicep build infra/main.bicep --stdout` | 0 | 1.2s |
| 2 | `azd provision --preview --environment dev` | 0 | 8.4s |

### Tool Versions

| Tool | Version |
|------|---------|
| Azure CLI | 2.76.0 |
| Bicep CLI | 0.25.3 |
| Azure Developer CLI | 1.9.0 |

---

## Issues

### Warnings

#### ⚠️ Nested Template Limit Reached

- **Severity:** Warning
- **Source:** what-if
- **Message:** 1 resource was ignored because nested template expansion limits were reached
- **Recommendation:** Review the ignored resource manually after deployment

---

## What-If Results

### Change Summary

| Change Type | Count |
|-------------|-------|
| 🆕 Create | 3 |
| 📝 Modify | 1 |
| 🗑️ Delete | 0 |
| ✓ No Change | 2 |
| ⚠️ Ignore | 1 |

### Resources to Create

| Resource Type | Resource Name |
|---------------|---------------|
| Microsoft.Resources/resourceGroups | rg-myapp-dev |
| Microsoft.Storage/storageAccounts | stmyappdev |
| Microsoft.Web/sites | app-myapp-dev |

### Resources to Modify

#### Microsoft.KeyVault/vaults/kv-myapp-dev

| Property | Current Value | New Value |
|----------|---------------|-----------|
| properties.sku.name | standard | premium |
| tags.environment | staging | dev |

### Resources to Delete

*No resources will be deleted.*

---

## Recommendations

1. Review the storage account name `stmyappdev` to ensure it meets naming requirements
2. Confirm the Key Vault SKU upgrade from standard to premium is intentional
3. The ignored nested template resource should be verified after deployment

---

## Next Steps

The preflight validation passed with warnings. Review the warnings above, then proceed:

azd provision --environment dev

---

*Report generated by Azure Deployment Preflight Skill*

---

Formatting Guidelines

1. Use consistent emoji for visual scanning 2. Include line numbers when referencing Bicep errors 3. Provide actionable remediation for each issue 4. Link to documentation when available 5. Order issues by severity (errors first, then warnings) 6. Include command examples in Next Steps

Validation Commands Reference

This reference documents all commands used for Azure deployment preflight validation.

Azure Developer CLI (azd)

azd provision --preview

Preview infrastructure changes for azd projects without deploying.

azd provision --preview [options]

Options:

Examples:

# Preview with default environment
azd provision --preview

# Preview specific environment
azd provision --preview --environment dev

# Preview without prompts (CI/CD)
azd provision --preview --no-prompt

Output: Shows resources that will be created, modified, or deleted.

azd auth login

Authenticate to Azure for azd operations.

azd auth login [options]

Options:

azd env list

List available environments.

azd env list

---

Azure CLI (az)

az deployment group what-if

Preview changes for resource group deployments.

az deployment group what-if \
  --resource-group <rg-name> \
  --template-file <bicep-file> \
  [options]

Required Parameters:

Optional Parameters:

Validation Levels:

Examples:

# Basic what-if
az deployment group what-if \
  --resource-group my-rg \
  --template-file main.bicep

# With parameters and full validation
az deployment group what-if \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters main.bicepparam \
  --validation-level Provider

# Fallback without RBAC checks
az deployment group what-if \
  --resource-group my-rg \
  --template-file main.bicep \
  --validation-level ProviderNoRbac

# JSON output for parsing
az deployment group what-if \
  --resource-group my-rg \
  --template-file main.bicep \
  --no-pretty-print

az deployment sub what-if

Preview changes for subscription-level deployments.

az deployment sub what-if \
  --location <location> \
  --template-file <bicep-file> \
  [options]

Required Parameters:

Examples:

az deployment sub what-if \
  --location eastus \
  --template-file main.bicep \
  --parameters main.bicepparam \
  --validation-level Provider

az deployment mg what-if

Preview changes for management group deployments.

az deployment mg what-if \
  --location <location> \
  --management-group-id <mg-id> \
  --template-file <bicep-file> \
  [options]

Required Parameters:

az deployment tenant what-if

Preview changes for tenant-level deployments.

az deployment tenant what-if \
  --location <location> \
  --template-file <bicep-file> \
  [options]

Required Parameters:

az login

Authenticate to Azure CLI.

az login [options]

Options:

az account show

Display current subscription context.

az account show

az group exists

Check if resource group exists.

az group exists --name <rg-name>

---

Bicep CLI

bicep build

Compile Bicep to ARM JSON and validate syntax.

bicep build <bicep-file> [options]

Options:

Examples:

# Validate syntax (output to stdout, no file created)
bicep build main.bicep --stdout > /dev/null

# Build to specific directory
bicep build main.bicep --outdir ./build

# Validate multiple files
for f in *.bicep; do bicep build "$f" --stdout; done

Error Output Format:

/path/to/file.bicep(22,51) : Error BCP064: Found unexpected tokens in interpolated expression.
/path/to/file.bicep(22,51) : Error BCP004: The string at this location is not terminated.

Format: <file>(<line>,<column>) : <severity> <code>: <message>

bicep --version

Check Bicep CLI version.

bicep --version

---

Parameter File Detection

Bicep Parameters (.bicepparam)

Modern Bicep parameter files (recommended):

using './main.bicep'

param location = 'eastus'
param environment = 'dev'
param tags = {
  environment: 'dev'
  project: 'myapp'
}

Detection pattern: <template-name>.bicepparam

JSON Parameters (.parameters.json)

Traditional ARM parameter files:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": { "value": "eastus" },
    "environment": { "value": "dev" }
  }
}

Detection patterns:

• <template-name>.parameters.json
• parameters.json
• parameters/<env>.json

Using Parameters with Commands

# Bicep parameters file
az deployment group what-if \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters main.bicepparam

# JSON parameters file
az deployment group what-if \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters @parameters.json

# Inline parameter overrides
az deployment group what-if \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters main.bicepparam \
  --parameters location=westus

---

Determining Deployment Scope

Check the Bicep file's targetScope declaration:

// Resource Group (default if not specified)
targetScope = 'resourceGroup'

// Subscription
targetScope = 'subscription'

// Management Group
targetScope = 'managementGroup'

// Tenant
targetScope = 'tenant'

Scope to Command Mapping:

---

Version Requirements

Check versions:

az --version
azd version
bicep --version