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:

…