azv-bicep-whatif

Compare Bicep templates against a live Azure environment by querying Azure directly and parsing the Bicep template. Reports resources that will be created, modified, deleted, or left unchanged — without using ARM what-if. > **Approach**: This skill does NOT use `az deployment group what-if`. Instead it: > 1. Parses the Bicep template and parameter file to build an **expected resource model** > 2. Queries Azure directly using `az resource list` and per-resource `az <service> show` commands to build an **actual resource model** > 3. Compares both models to identify existence-level and property-level differences **Input**: A solution folder containing Bicep templates (`main.bicep`) and a `.bicepparam` file, plus an Azure target scope (resource group name or subscription ID). The user can specify these, or the skill will auto-discover and prompt for missing inputs. **Tools required**: File system tools (read files), Terminal (for running `az` CLI commands), Azure MCP server tools **Reference files**: - `.github/skills/shared/azure-resource-model.md` — Shared resource metadata model definition - `.github/skills/shared/azure-resource-configs.md` — Per-resource-type configuration schemas (useful for interpreting property changes) - `.github/skills/shared/data/azure-property-paths.json` — Azure Property Retrieval Mapping (tracked properties, ARM JSON paths, defaults, severity classifications) **Shared procedures** (MUST follow): - `.github/skills/shared/procedures/azure-authentication.md` — Azure session check procedure - `.github/skills/shared/procedures/bicep-parsing.md` — Bicep template parsing procedure --- ## Steps ### 1. Check Azure Authentication Follow the procedure in `.github/skills/shared/procedures/azure-authentication.md`. **HARD GATE** — stop if not authenticated. ### 2. Accept Inputs Identify the solution folder, the Bicep template, the parameter file, and the target scope. #### 2a. Identify the Solution Folder **If the user specifies a folder path:** - Verify the folder exists - Use it as the solution folder **If no folder is specified:** - Search the workspace for folders containing a `main.bicep` file - If exactly one is found, use it (announce which folder) - If multiple are found, present the list and ask the user to select one - If none are found, ask the user to provide a solution folder #### 2b. Identify the Bicep Template - Verify `main.bicep` exists in the solution folder - If not found, report an error: ``` ## No Bicep Template Found No `main.bicep` file found in `<folder-path>`. This skill requires a Bicep template to run the what-if analysis. ``` - Stop execution #### 2c. Identify the Parameter File **If exactly one `.bicepparam` file exists in the solution folder:** - Use it as the parameter file (announce which file) **If multiple `.bicepparam` files exist:** - Present the list and ask the user to select one: ``` ## Multiple Parameter Files Found Found multiple `.bicepparam` files in `<folder-path>`: 1. `app-dev.bicepparam` 2. `app-prod.bicepparam` Which parameter file should I use? (1/2) ``` - Wait for user selection **If no `.bicepparam` file exists:** - Warn the user: ``` ⚠️ No `.bicepparam` file found in `<folder-path>`. Default parameter values from `azure-property-paths.json` will be used as expected values. ``` - Proceed without a parameter file #### 2d. Identify the Target Scope **If the user specifies a resource group name:** - Use it as the target scope - Verify the resource group exists: run `az group show --name <name>` — if this fails, report an error and stop **If the user specifies a subscription ID:** - Use it as the target scope for a subscription-level comparison **If no scope is specified, try to infer it:** 1. **From the `.bicepparam` file**: Look for a `using` declaration or comments indicating the target resource group 2. **If a resource group name is found**, propose it: ``` The `.bicepparam` file references resource group `<name>`. Use this as the target scope? (yes/no) ``` 3. **If no scope can be inferred**, ask the user: ``` Which Azure resource group should I compare the templates against? ``` - Wait for user input ### 3. Parse Templates into Expected Resource Model Read the Bicep template and parameter file to build an **expected resource model** — what the templates declare should exist. **3a. Read and parse the `.bicepparam` file** Read the `.bicepparam` file and extract all parameter values. These are the user-specified values that override defaults. For each `param <name> = <value>` line, record the name and resolved value. **3b. Read and parse `main.bicep` and all module files** Read `main.bicep` and every Bicep module it references in `modules/`. For each resource block that is either declared inline or inside a module, extract: - **Resource type** (e.g., `Microsoft.Web/sites`) - **Resource name** — resolve from parameter values in the `.bicepparam` file if the name is a parameter reference (e.g., `name: appServiceName` → resolve `appServiceName` to its value) - **Key properties** — extract any properties that map to tracked properties in `.github/skills/shared/data/azure-property-paths.json` for this resource type (e.g., `sku.name`, `properties.siteConfig.linuxFxVersion`, `properties.httpsOnly`) - **Relationships** — note explicit references between resources (e.g., App Service → App Service Plan via `serverFarmId`) For properties that reference parameters (e.g., `linuxFxVersion: appServiceRuntimeStack`), resolve them using the `.bicepparam` values. If the parameter has no value in `.bicepparam`, use the default from `azure-property-paths.json`. **3c. Build the expected resource model** Produce a structured model (as defined in `.github/skills/shared/azure-resource-model.md`) with all declared resources and their resolved property values. This is the "desired state" from the templates. Display a summary of what was parsed: ``` ## Template Resources Parsed **N resources** from `<solution-folder>/main.bicep`: | # | Resource | Type | Key Properties | |---|----------|------|----------------| | 1 | vnet-01 | Microsoft.Network/virtualNetworks | addressPrefix: 10.0.0.0/16 | | 2 | vm-01 | Microsoft.Compute/virtualMachines | vmSize: Standard_B2s | | 3 | webapp-azverify | Microsoft.Web/sites | runtime: DOTNET\|10.0, httpsOnly: true | ``` ### 4. Check Resource Provider Registration Before querying Azure, verify that all resource providers required by the Bicep template are registered in the active subscription. Unregistered providers will cause deployment failures. **4a. Extract required provider namespaces** From the expected resource model (Step 3), extract a unique list of top-level resource provider namespaces. Derive the namespace from each resource type by taking the first segment (e.g., `Microsoft.Compute/virtualMachines` → `Microsoft.Compute`, `Microsoft.Network/virtualNetworks` → `Microsoft.Network`). **4b. Query registered providers** Run: ```bash az provider list --query "[?registrationState=='Registered'].namespace" -o json ``` This returns all currently registered provider namespaces in the subscription. **4c. Compare and report** Compare the required namespaces (4a) against the registered namespaces (4b) using case-insensitive matching. **If all providers are registered:** - Continue to Step 5 (no message needed) **If one or more providers are NOT registered:** - Display a warning with registration commands: ``` ## ⚠️ Unregistered Resource Providers The following resource providers are **required by the Bicep template** but are **not registered** in subscription `<sub-name>` (`<sub-id>`). Deployment will fail unless they are registered first. | # | Provider Namespace | Required By | |---|-------------------|-------------| | 1 | Microsoft.App | my-container-app (Microsoft.App/containerApps) | | 2 | Microsoft.Cache | my-redis (Microsoft.Cache/redis) | **To register the missing providers, run:** ```bash az provider register --namespace Microsoft.App az provider register --namespace Microsoft.Cache ``` > **Note:** Provider registration can take a few minutes. Check status with: > ```bash > az provider show --namespace <namespace> --query registrationState -o tsv > ``` ``` - **Continue execution** — this is a warning, not a hard gate. The what-if comparison is still valuable for planning. ### 5. Query Azure for Actual Resource Model Query the target resource group to build an **actual resource model** — what is currently deployed in Azure. **5a. List all resources in the target scope** Run: ```bash az resource list --resource-group <rg-name> -o json ``` This returns all resources currently in the resource group. Build an initial resource model from the results. **Exclude infrastructure-only resources** that are auto-created by Azure and not declared in Bicep templates: - `Microsoft.Compute/disks` that are OS disks (managed by VMs) - `Microsoft.Network/networkInterfaces` that are PE-managed NICs (where `managedBy` is set to a Private Endpoint) - `Microsoft.Network/networkWatchers` — auto-created by Azure - `microsoft.alertsManagement/smartDetectorAlertRules` — auto-created - `Microsoft.Portal/dashboards` — portal artifacts **5b. Retrieve full properties for each resource** For each resource, retrieve full properties using the most specific CLI command available: - Use resource-specific commands where available: `az vm show`, `az webapp show`, `az appservice plan show`, `az network vnet show`, `az network vnet subnet show`, `az network nic show`, `az network private-endpoint show`, `az network private-dns zone show`, `az storage account show`, `az keyvault show`, `az redis show`, `az cosmosdb show`, `az sql server show`, `az acr show`, `az containerapp show` - Fall back to `az resource show --ids <resourceId> -o json` for child resources or types without specific CLI commands - All commands use `--ids <resourceId> -o json` Show progress: `Querying Azure resources (1/N): vnet-01...` **5c. Extract tracked properties from query results** For each resource, extract the property values that correspond to the tracked properties in `azure-property-paths.json` for that resource type. Use the ARM JSON paths from the mapping to navigate the JSON response. ### 6. Compare Models and Classify Changes Compare the expected resource model (Step 3) against the actual Azure resource model (Step 5) to classify each resource. **6a. Existence-level classification** Match resources by type AND name (case-insensitive). Classify each resource as: - **Create** — in the template but NOT in Azure (resource will be created when deployed) - **Modify** — in both template and Azure, but with property differences - **Delete** — in Azure but NOT in the template (resource would be removed if template is authoritative) - **No Change** — in both template and Azure, with all tracked properties matching **Matching rules:** - Match by resource type and name (case-insensitive) - For child resources (subnets, DNS zone links, etc.), match within their parent's context - If only one resource of a given type exists in each model and names differ slightly, match them — report as "Modify (name differs)" **6b. Property-level comparison (for matched resources)** For resources matched in both models, compare each tracked property from `azure-property-paths.json`: 1. **Expected value**: use the resolved value from the template (Step 3b); if not specified, use the default from `azure-property-paths.json` 2. **Actual value**: the value retrieved from Azure (Step 5c) 3. Apply **normalization rules** before comparing: - Case-insensitive string comparison for enum-like values (SKU names, tiers, regions) - Boolean normalization: `true`/`"true"`/`"True"` all equal `true` - Empty collection equivalence: `[]`, `null`, absent → all equivalent for array properties - Numeric string normalization: `"30"` equals `30` 4. If normalized expected ≠ normalized actual, record as a **property difference** with: - Property name - Current value (Azure) - Expected value (template) - Severity from `azure-property-paths.json` **6c. Classify final change type** After property comparison, refine the classification: - **No Change** — resource exists in Azure and all tracked properties match the template - **Modify** — resource exists in Azure but one or more tracked properties differ (list the diffs) - **Create** — resource is in the template but not found in Azure - **Delete** — resource is in Azure but not in the template ### 7. Present Change Report Display a categorized comparison report. **Header** (always shown): Title, target scope, template/parameters paths, summary table with counts per category (🆕 Create, ✏️ Modify, 🗑️ Delete, ✅ No Change). **If no changes**: Show "✅ No changes — all template resources match Azure" and stop. **Per-category sections**: - **🆕 Create**: Table of resources in template but not in Azure (columns: #, Resource, Type, Resource Group) - **✏️ Modify**: Per-resource property diff tables (columns: Property, Current Azure Value, Template Value, Severity). Severity levels from `azure-property-paths.json`. - **🗑️ Delete**: Table of resources in Azure but not in template, with warning about authoritative deployment - **✅ No Change**: Collapsible `<details>` section listing matched resources ### 8. Offer Next Steps If deletions detected, warn user to verify intentional exclusions and check diagram with azv-bicep-diagram-sync. When changes exist, suggest: deploy command (`az deployment group create`), review Critical severity items, and sync check with azv-bicep-diagram-sync.