Azure Deployment Preflight

---
name: azure-deployment-preflight
description: 'Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision.'
---

# 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:

```bash
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:

```bash
azd provision --preview
```

If an environment is specified or multiple environments exist:
```bash
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:**

```bash
# 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`:

```bash
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](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](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:
```bash
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](references/VALIDATION-COMMANDS.md)
- [Report Template](references/REPORT-TEMPLATE.md)
- [Error Handling Guide](references/ERROR-HANDLING.md)

# 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:**
```markdown
#### ❌ 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:**
```markdown
#### ❌ 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:**
```markdown
#### ⚠️ 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:**
```markdown
#### ❌ 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:
  ```bash
  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:**
```markdown
#### ❌ 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:**
```markdown
#### ⏭️ 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:**
```markdown
#### ⏭️ 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:
```markdown
## 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

| Tool | Exit Code | Meaning |
|------|-----------|---------|
| az | 0 | Success |
| az | 1 | General error |
| az | 2 | Command not found |
| az | 3 | Required argument missing |
| azd | 0 | Success |
| azd | 1 | Error |
| bicep | 0 | Build succeeded |
| bicep | 1 | Build failed (errors) |
| bicep | 2 | Build succeeded with warnings |

# Preflight Report Template

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

---

## Template

```markdown
# 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:**
```bash
azd provision
# or
azd up
```

**For standalone Bicep:**
```bash
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

| Status | Meaning | Visual |
|--------|---------|--------|
| **Pass** | All checks succeeded, safe to deploy | ✅ |
| **Pass with Warnings** | Checks succeeded but review warnings | ⚠️ |
| **Fail** | One or more checks failed | ❌ |

### Individual Check Status

| Status | Meaning |
|--------|---------|
| ✅ Pass | Check completed successfully |
| ❌ Fail | Check found errors |
| ⚠️ Warnings | Check passed with warnings |
| ⏭️ Skipped | Check was skipped (tool unavailable, etc.) |

---

## Example Report

```markdown
# 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:

```bash
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.

```bash
azd provision --preview [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--environment`, `-e` | Name of the environment to use |
| `--no-prompt` | Accept defaults without prompting |
| `--debug` | Enable debug logging |
| `--cwd` | Set working directory |

**Examples:**

```bash
# 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.

```bash
azd auth login [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--check-status` | Check login status without logging in |
| `--use-device-code` | Use device code flow |
| `--tenant-id` | Specify tenant |
| `--client-id` | Service principal client ID |

### azd env list

List available environments.

```bash
azd env list
```

---

## Azure CLI (az)

### az deployment group what-if

Preview changes for resource group deployments.

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

**Required Parameters:**
| Parameter | Description |
|-----------|-------------|
| `--resource-group`, `-g` | Target resource group name |
| `--template-file`, `-f` | Path to Bicep file |

**Optional Parameters:**
| Parameter | Description |
|-----------|-------------|
| `--parameters`, `-p` | Parameter file or inline values |
| `--validation-level` | `Provider` (default), `ProviderNoRbac`, or `Template` |
| `--result-format` | `FullResourcePayloads` (default) or `ResourceIdOnly` |
| `--no-pretty-print` | Output raw JSON for parsing |
| `--name`, `-n` | Deployment name |
| `--exclude-change-types` | Exclude specific change types from output |

**Validation Levels:**
| Level | Description | Use Case |
|-------|-------------|----------|
| `Provider` | Full validation with RBAC checks | Default, most thorough |
| `ProviderNoRbac` | Full validation, read permissions only | When lacking deploy permissions |
| `Template` | Static syntax validation only | Quick syntax check |

**Examples:**

```bash
# 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.

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

**Required Parameters:**
| Parameter | Description |
|-----------|-------------|
| `--location`, `-l` | Location for deployment metadata |
| `--template-file`, `-f` | Path to Bicep file |

**Examples:**

```bash
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.

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

**Required Parameters:**
| Parameter | Description |
|-----------|-------------|
| `--location`, `-l` | Location for deployment metadata |
| `--management-group-id`, `-m` | Target management group ID |
| `--template-file`, `-f` | Path to Bicep file |

### az deployment tenant what-if

Preview changes for tenant-level deployments.

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

**Required Parameters:**
| Parameter | Description |
|-----------|-------------|
| `--location`, `-l` | Location for deployment metadata |
| `--template-file`, `-f` | Path to Bicep file |

### az login

Authenticate to Azure CLI.

```bash
az login [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--tenant`, `-t` | Tenant ID or domain |
| `--use-device-code` | Use device code flow |
| `--service-principal` | Login as service principal |

### az account show

Display current subscription context.

```bash
az account show
```

### az group exists

Check if resource group exists.

```bash
az group exists --name <rg-name>
```

---

## Bicep CLI

### bicep build

Compile Bicep to ARM JSON and validate syntax.

```bash
bicep build <bicep-file> [options]
```

**Options:**
| Option | Description |
|--------|-------------|
| `--stdout` | Output to stdout instead of file |
| `--outdir` | Output directory |
| `--outfile` | Output file path |
| `--no-restore` | Skip module restore |

**Examples:**

```bash
# 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.

```bash
bicep --version
```

---

## Parameter File Detection

### Bicep Parameters (.bicepparam)

Modern Bicep parameter files (recommended):

```bicep
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:

```json
{
  "$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

```bash
# 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:

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

// Subscription
targetScope = 'subscription'

// Management Group
targetScope = 'managementGroup'

// Tenant
targetScope = 'tenant'
```

**Scope to Command Mapping:**

| targetScope | Command | Required Parameters |
|-------------|---------|---------------------|
| `resourceGroup` | `az deployment group what-if` | `--resource-group` |
| `subscription` | `az deployment sub what-if` | `--location` |
| `managementGroup` | `az deployment mg what-if` | `--location`, `--management-group-id` |
| `tenant` | `az deployment tenant what-if` | `--location` |

---

## Version Requirements

| Tool | Minimum Version | Recommended Version | Key Features |
|------|-----------------|---------------------|--------------|
| Azure CLI | 2.14.0 | 2.76.0+ | `--validation-level` switch |
| Azure Developer CLI | 1.0.0 | Latest | `--preview` flag |
| Bicep CLI | 0.4.0 | Latest | Best error messages |

**Check versions:**
```bash
az --version
azd version
bicep --version
```