williamlimasilva/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:

| Target Scope | Command | |--------------|---------| | resourceGroup (default) | az deployment group what-if | | subscription | az deployment sub what-if | | managementGroup | az deployment mg what-if | | tenant | az deployment tenant what-if |

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:

| Change Type | Symbol | Meaning | |-------------|--------|---------| | Create | + | New resource will be created | | Delete | - | Resource will be deleted | | Modify | ~ | Resource properties will change | | NoChange | = | Resource unchanged | | Ignore | * | Resource not analyzed (limits reached) | | Deploy | ! | Resource will be deployed (changes unknown) |

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:

| Information | Required For | How to Obtain | |-------------|--------------|---------------| | Resource Group | az deployment group | Ask user or check existing .azure/ config | | Subscription | All deployments | az account show or ask user | | Location | Sub/MG/Tenant scope | Ask user or use default from config | | Environment | azd projects | azd env list or ask user |

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.

| Error Type | Action | |------------|--------| | Not logged in | Note in report, suggest az login or azd auth login | | Permission denied | Fall back to ProviderNoRbac, note in report | | Bicep syntax error | Include all errors, continue to other files | | Tool not installed | Note in report, skip that validation step | | Resource group not found | Note in report, suggest creating it |

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