Azure deployment preflight
Validate Bicep infrastructure before deployment by detecting the workflow, running syntax and preview commands, categorizing what-if changes, and writing a preflight-report.md with actionable issues.
When to invoke
- "Validate my Bicep deployment before I run it."
- "Preview what azd provision will change."
- "Run Azure what-if for this template."
- "Check whether I have permission to deploy this infrastructure."
- "Prepare for azd up or az deployment."
Prerequisites and context
| Tool or value |
Required for |
How to check or obtain |
az |
Standalone Azure CLI what-if |
az --version; az account show for subscription. |
azd |
Projects with azure.yaml |
azd version; azd env list for environments. |
bicep |
Local syntax validation |
bicep --version; fallback to Azure validation if absent. |
| Resource group |
az deployment group what-if |
Ask user or check existing .azure/ config. |
| Subscription |
All deployments |
az account show or ask user. |
| Location |
sub, mg, or tenant scope |
Ask user or use default from config. |
| Environment |
azd projects |
azd env list or user input. |
Procedure
- Detect project type: if
azure.yaml exists, use the azd workflow; otherwise use the Azure CLI workflow.
- Locate
.bicep files. For azd, check infra/ before the project root. For standalone deployments, use the user's file or search infra/, deploy/, and the root.
- Match parameter files in this order:
<filename>.bicepparam, <filename>.parameters.json, parameters.json, then parameters/<env>.json in the same area.
- Run syntax validation for each Bicep file:
bicep build <bicep-file> --stdout. Capture line and column errors, warnings, and build status. If bicep is not installed, note it and continue.
- Run the deployment preview. Continue after failures and capture every issue.
- Parse what-if change symbols and property changes.
- Write
preflight-report.md in the project root using references/REPORT-TEMPLATE.md.
Preview commands
| Workflow or scope |
Command |
azd default environment |
azd provision --preview |
azd named environment |
azd provision --preview --environment <env-name> |
resourceGroup target scope |
az deployment group what-if --resource-group <rg-name> --template-file <bicep-file> --parameters <param-file> --validation-level Provider |
subscription target scope |
az deployment sub what-if --location <location> --template-file <bicep-file> --parameters <param-file> --validation-level Provider |
managementGroup target scope |
az deployment mg what-if --location <location> --management-group-id <mg-id> --template-file <bicep-file> --parameters <param-file> --validation-level Provider |
tenant target scope |
az deployment tenant what-if --location <location> --template-file <bicep-file> --parameters <param-file> --validation-level Provider |
| RBAC fallback |
Retry with --validation-level ProviderNoRbac and state that full permission validation did not run. |
What-if interpretation
| Change type |
Symbol |
Meaning |
Report detail |
| Create |
+ |
New resource will be created |
Resource type, name, location. |
| Delete |
- |
Existing resource will be deleted |
Mark as high risk unless intentional. |
| Modify |
~ |
Properties will change |
Include property names and before/after values when available. |
| NoChange |
= |
Resource unchanged |
Count only unless the user asked for full inventory. |
| Ignore |
* |
Resource not analyzed because limits were reached |
Warn that the preview is incomplete. |
| Deploy |
! |
Resource will be deployed but changes are unknown |
Require manual inspection. |
Error handling
Continue validation even when errors occur; the report should contain all failures and warnings.
| Error type |
Action |
| Not logged in |
Note in report; suggest az login or azd auth login. |
| Permission denied |
Retry what-if with ProviderNoRbac; note missing RBAC validation. |
| Bicep syntax error |
Include every error; continue to other files. |
| Tool not installed |
Note in report and skip only that validation step. |
| Resource group not found |
Note in report; suggest creating it or selecting the correct group. |
Progressive disclosure and bundled resources
references/VALIDATION-COMMANDS.md: detailed command variants and flags.references/REPORT-TEMPLATE.md: required preflight-report.md structure.references/ERROR-HANDLING.md: detailed remediation guidance.
Command and scope vocabulary
Preserve Azure deployment terminology exactly when reporting: azd up, azd provision, az deployment, az deployment group, az deployment sub what-if, az deployment mg what-if, az deployment tenant what-if, --validation-level, --validation-level Provider, targetScope, Sub/MG/Tenant, JSON, line/column, success/failure, and create/modify/delete/unchanged.
Use concrete examples when they match the repository: infra/main.bicep, infra/main.bicepparam, and bicep build infra/main.bicep --stdout.
Output template
## Azure deployment preflight
**Status:** pass | issues found | blocked
**Report:** `preflight-report.md`
**Workflow:** azd | az cli
**Target scope:** resourceGroup | subscription | managementGroup | tenant | unknown
### Tools executed
| Tool | Command | Result |
| --- | --- | --- |
| Bicep | `bicep build <bicep-file> --stdout` | <pass/fail/skipped> |
| Preview | `<azd provision --preview or az deployment ... what-if>` | <pass/fail> |
### What-if summary
| Symbol | Count | Notes |
| --- | --- | --- |
| `+` | <count> | <created resources> |
| `~` | <count> | <modified resources> |
| `-` | <count> | <deleted resources> |
### Issues
- <severity>: <error, warning, permission gap, or missing input>
Quality gate
1---2name: azure-deployment-preflight-23description: Validate Azure Bicep deployments before execution with syntax checks, azd preview, Azure CLI what-if, validation-level fallback, permission checks, and a preflight report. Use this skill when the user asks before azd up, azd provision, az deployment, Bicep deployment, infrastructure review, permission verification, or what-if change preview.4---56# Azure deployment preflight78Validate Bicep infrastructure before deployment by detecting the workflow, running syntax and preview commands, categorizing what-if changes, and writing a `preflight-report.md` with actionable issues.910## When to invoke1112- "Validate my Bicep deployment before I run it."13- "Preview what azd provision will change."14- "Run Azure what-if for this template."15- "Check whether I have permission to deploy this infrastructure."16- "Prepare for azd up or az deployment."1718## Prerequisites and context1920| Tool or value | Required for | How to check or obtain |21| --- | --- | --- |22| `az` | Standalone Azure CLI what-if | `az --version`; `az account show` for subscription. |23| `azd` | Projects with `azure.yaml` | `azd version`; `azd env list` for environments. |24| `bicep` | Local syntax validation | `bicep --version`; fallback to Azure validation if absent. |25| Resource group | `az deployment group what-if` | Ask user or check existing `.azure/` config. |26| Subscription | All deployments | `az account show` or ask user. |27| Location | `sub`, `mg`, or `tenant` scope | Ask user or use default from config. |28| Environment | `azd` projects | `azd env list` or user input. |2930## Procedure31321. Detect project type: if `azure.yaml` exists, use the `azd` workflow; otherwise use the Azure CLI workflow.332. Locate `.bicep` files. For `azd`, check `infra/` before the project root. For standalone deployments, use the user's file or search `infra/`, `deploy/`, and the root.343. Match parameter files in this order: `<filename>.bicepparam`, `<filename>.parameters.json`, `parameters.json`, then `parameters/<env>.json` in the same area.354. Run syntax validation for each Bicep file: `bicep build <bicep-file> --stdout`. Capture line and column errors, warnings, and build status. If `bicep` is not installed, note it and continue.365. Run the deployment preview. Continue after failures and capture every issue.376. Parse what-if change symbols and property changes.387. Write `preflight-report.md` in the project root using `references/REPORT-TEMPLATE.md`.3940## Preview commands4142| Workflow or scope | Command |43| --- | --- |44| `azd` default environment | `azd provision --preview` |45| `azd` named environment | `azd provision --preview --environment <env-name>` |46| `resourceGroup` target scope | `az deployment group what-if --resource-group <rg-name> --template-file <bicep-file> --parameters <param-file> --validation-level Provider` |47| `subscription` target scope | `az deployment sub what-if --location <location> --template-file <bicep-file> --parameters <param-file> --validation-level Provider` |48| `managementGroup` target scope | `az deployment mg what-if --location <location> --management-group-id <mg-id> --template-file <bicep-file> --parameters <param-file> --validation-level Provider` |49| `tenant` target scope | `az deployment tenant what-if --location <location> --template-file <bicep-file> --parameters <param-file> --validation-level Provider` |50| RBAC fallback | Retry with `--validation-level ProviderNoRbac` and state that full permission validation did not run. |5152## What-if interpretation5354| Change type | Symbol | Meaning | Report detail |55| --- | --- | --- | --- |56| Create | `+` | New resource will be created | Resource type, name, location. |57| Delete | `-` | Existing resource will be deleted | Mark as high risk unless intentional. |58| Modify | `~` | Properties will change | Include property names and before/after values when available. |59| NoChange | `=` | Resource unchanged | Count only unless the user asked for full inventory. |60| Ignore | `*` | Resource not analyzed because limits were reached | Warn that the preview is incomplete. |61| Deploy | `!` | Resource will be deployed but changes are unknown | Require manual inspection. |6263## Error handling6465Continue validation even when errors occur; the report should contain all failures and warnings.6667| Error type | Action |68| --- | --- |69| Not logged in | Note in report; suggest `az login` or `azd auth login`. |70| Permission denied | Retry what-if with `ProviderNoRbac`; note missing RBAC validation. |71| Bicep syntax error | Include every error; continue to other files. |72| Tool not installed | Note in report and skip only that validation step. |73| Resource group not found | Note in report; suggest creating it or selecting the correct group. |7475## Progressive disclosure and bundled resources7677- `references/VALIDATION-COMMANDS.md`: detailed command variants and flags.78- `references/REPORT-TEMPLATE.md`: required `preflight-report.md` structure.79- `references/ERROR-HANDLING.md`: detailed remediation guidance.8081## Command and scope vocabulary8283Preserve Azure deployment terminology exactly when reporting: `azd up`, `azd provision`, `az deployment`, `az deployment group`, `az deployment sub what-if`, `az deployment mg what-if`, `az deployment tenant what-if`, `--validation-level`, `--validation-level Provider`, `targetScope`, `Sub/MG/Tenant`, `JSON`, `line/column`, `success/failure`, and `create/modify/delete/unchanged`.8485Use concrete examples when they match the repository: `infra/main.bicep`, `infra/main.bicepparam`, and `bicep build infra/main.bicep --stdout`.8687## Output template8889```markdown90## Azure deployment preflight9192**Status:** pass | issues found | blocked93**Report:** `preflight-report.md`94**Workflow:** azd | az cli95**Target scope:** resourceGroup | subscription | managementGroup | tenant | unknown9697### Tools executed98| Tool | Command | Result |99| --- | --- | --- |100| Bicep | `bicep build <bicep-file> --stdout` | <pass/fail/skipped> |101| Preview | `<azd provision --preview or az deployment ... what-if>` | <pass/fail> |102103### What-if summary104| Symbol | Count | Notes |105| --- | --- | --- |106| `+` | <count> | <created resources> |107| `~` | <count> | <modified resources> |108| `-` | <count> | <deleted resources> |109110### Issues111- <severity>: <error, warning, permission gap, or missing input>112```113114## Quality gate115116- [ ] Project type was detected from `azure.yaml` or absence of it.117- [ ] Bicep files and matching parameter files were located and reported.118- [ ] `bicep build <bicep-file> --stdout` was run or its absence was documented.119- [ ] The correct `azd provision --preview` or `az deployment ... what-if` scope was selected.120- [ ] `--validation-level ProviderNoRbac` fallback was used only after permission failure and was reported.121- [ ] What-if symbols `+`, `-`, `~`, `=`, `*`, and `!` were interpreted correctly.122- [ ] `preflight-report.md` was created in the project root or the blocker is explicit.123- [ ] Referenced bundled resources exist and were used on demand.
paulasilvatech