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

Quick Pre-flight Checks

Run these checks BEFORE any deployment to avoid mid-deployment failures:

1. •Tools installed: az, azd, docker, bicep
2. •Authentication valid: az account show and azd auth login
3. •Subscription quotas sufficient: Check resource limits
4. •Docker daemon running (for container deployments)

# Verify tools
az --version
azd version
bicep --version
docker info

# Verify authentication
az account show
azd auth login --check-status

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 1.5: Validate azure.yaml (azd projects only)

For azd projects, validate the azure.yaml configuration using the Azure MCP azd tool:

const validation = await azure-azd({
  command: "validate_azure_yaml",
  parameters: { path: "./azure.yaml" }
});

What to capture:

• •Schema validation errors
• •Invalid service configurations
• •Missing required fields

If validation fails, include errors in the report and continue to Step 2.

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

Azure MCP azd Tools

Use the Azure MCP server's azd tools (azure-azd) for additional validation:

Validate azure.yaml before running azd provision --preview:

const validation = await azure-azd({
  command: "validate_azure_yaml",
  parameters: { path: "./azure.yaml" }
});

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 validates azure.yaml using azure-azd → validate_azure_yaml
4. •Agent finds infra/main.bicep and infra/main.bicepparam
5. •Agent runs bicep build infra/main.bicep --stdout
6. •Agent runs azd provision --preview
7. •Agent generates preflight-report.md in project root
8. •Agent summarizes findings to user

Reference Documentation

• •Validation Commands Reference
• •Report Template
• •Error Handling Guide