--- name: azv-azure-to-bicep description: Reverse-engineer a live Azure scope (resource group or filtered subscription) into deployment-ready, modular Bicep templates with parameter files. Use when the user wants to bring existing Azure infrastructure under Bicep/IaC management. license: MIT compatibility: Requires an authenticated Azure session (CLI, Az PowerShell, or Azure MCP). metadata: version: "1.1" project: AzVerify --- Discover resources in a live Azure scope, extract their full configuration, and generate deployment-ready Bicep templates with modular structure, user-editable parameter files, and dependency documentation for external resources. **Input**: An Azure scope — a resource group name (primary) or a subscription ID with optional resource type filter. Optionally, a target environment hint (dev/prod) to influence default sizing in the parameter file. **Tools used**: File system tools (read/write files), Terminal (for running `az` CLI commands and PowerShell 7 / `pwsh` shared scripts), Azure Best Practices MCP (`azure-get_azure_bestpractices`), Bicep Schema MCP (`azure-bicepschema`), and Azure Documentation MCP (`azure-documentation`). ### Tool Preflight Before discovery, verify the capabilities used by this workflow: 1. Call `azure-get_azure_bestpractices` with `get_azure_bestpractices_get` for general code generation guidance. 2. Call `azure-bicepschema` with `bicepschema_get` for every resource type whose API version or deployable schema is uncertain. 3. Use `azure-documentation` search and fetch for current service guidance when a schema call does not answer the question. If a capability is unavailable, continue only when the matching shared reference plus Bicep CLI validation can provide the same check; report the fallback in the verification summary. ## Output Budget Rules Follow `.github/skills/shared/procedures/output-budget.md` strictly — this skill frequently handles 20-40+ resources and can hit the LLM response length limit. In addition to the shared rules: - **Build Bicep files directly.** Write generated code to files. Do NOT echo full Bicep/bicepparam content in the response — show only file paths and a summary of what was generated. - **Delete intermediate files on the skill's own schedule.** Intermediate extraction files (`extract-*.json`, `resource-list-raw.json`, and the temporary resource model JSON file) are never deliverables. Keep them available until Step 11 has written the README (it needs the resource counts and extraction stats), then delete them all in Step 12. Never leave the resource model JSON behind after the skill completes. ## Fallback: pwsh Unavailable If `pwsh`/`powershell.exe` or a shared script cannot be executed, use the fallback that matches the step you are on, then continue the workflow normally: | Step | Fallback source | |------|-----------------| | 1 — Auth check | MCP auth probe fallback in `.github/skills/shared/procedures/azure-authentication.md` | | 3 — Discovery | "Script/pwsh Unavailable — MCP Fallback" in `.github/skills/shared/azure-resource-configs.md` | | 4 — Filtering | Inline fallback in `.github/skills/shared/procedures/resource-filtering.md` | | 6a — Property extraction | "Script/pwsh Unavailable — MCP Fallback" in `.github/skills/shared/azure-resource-configs.md` | | 6b — Read-only stripping and secrets | Manual strip rules listed in Step 6b, using `.github/skills/shared/data/arm-readonly-properties.json` | | 7a — Relationships | "Manual Relationship Inference — Script Unavailable Fallback" in `.github/skills/shared/azure-resource-model.md` | Stop only if Azure MCP is also unavailable, using the prerequisite message in `.github/skills/shared/azure-resource-configs.md`. ## Steps ### 1. Check Azure Authentication Run `pwsh .github/skills/shared/scripts/Test-AzureAuth.ps1` — see `.github/skills/shared/procedures/azure-authentication.md` for the script contract. The script writes a JSON status object to stdout and exits non-zero when no Azure session is found. A **non-zero exit code is a HARD GATE**: present the authentication instructions from the contract doc and stop. *(If pwsh or the script is unavailable, see "Fallback: pwsh Unavailable".)* ### 2. Accept Inputs Identify the Azure scope to discover resources from. #### 2a. Identify the Azure Scope **If the user specifies a resource group name:** - Use that resource group as the discovery scope - Verify the resource group exists: run `az group show --name ` — if this fails, report an error and stop **If the user specifies a subscription ID:** - Use that subscription as the discovery scope - Note: subscription-level discovery can produce many resources — the skill will apply filtering and warnings (see Step 4) **If no scope is specified:** - Ask the user: ``` Which Azure resource group should I generate Bicep templates from? If you want subscription-level discovery, provide a subscription ID instead. ``` - Wait for user input #### 2b. Identify Optional Parameters **Target environment hint:** If the user specifies a target environment (e.g., "generate for dev" or "this will be production"): - Use this to influence default sizing in the `.bicepparam` comments (e.g., note the current size and suggest dev/prod alternatives) - If not specified, default to documenting the **current** Azure configuration as-is **Resource type filters:** If the user provides a resource type filter (e.g., "only compute and networking resources"): - Map the filter to Azure resource type prefixes (e.g., `Microsoft.Compute/*`, `Microsoft.Network/*`) - Apply these filters during discovery **Resource exclusions:** If the user wants to exclude specific resources or types: - Accept a list of resource names or type patterns to skip - Apply exclusions during the filtering step ### 3. Discover Azure Resources Enumerate all resources in the specified Azure scope. **3a. Resource group scope** Run the shared discovery script and write the resource model to a temporary JSON file in the output folder: ``` pwsh .github/skills/shared/scripts/Get-AzureResourceModel.ps1 -ResourceGroup -OutFile /resource-model.json ``` The script emits the shared resource model contract (`id`, `name`, `type`, `location`, `tags`, `sku`) documented in `.github/skills/shared/azure-resource-model.md`. Treat the emitted JSON as the source of truth for Steps 4-7. Do not print the model contents. Display progress: ``` ⏳ Discovering resources in resource group ``... ``` **3b. Subscription scope** Run the same script with `-SubscriptionId ` instead of `-ResourceGroup`. Pass user-specified resource type filters from Step 2b as a `-ResourceTypeFilter` parameter to the script if supported; otherwise filter the emitted JSON before writing to the temporary model file. These user filters are distinct from the Step 4 standard exclusion rules applied by `-Mode bicep`, which never handles user filters. **3c. Script/pwsh unavailable — MCP fallback** If `pwsh`/`powershell.exe` or the script cannot be executed, build the same resource model through Azure MCP as described in "Fallback: pwsh Unavailable" (list resources with `mcp_azure_group_resource_list`, then assemble the model shape by hand). **3d. Handle empty results** If no resources are found after discovery: ``` ## No Resources Found No resources were found in ``. If you expected resources here, verify: - The resource group name is spelled correctly - You're connected to the correct subscription (`az account show`) - Resources have been deployed to this scope - The authenticated identity has read permissions on this resource group ``` - Stop execution ### 4. Filter Non-Deployable Resources Run `pwsh .github/skills/shared/scripts/Select-AzureResources.ps1 -InputFile -Mode bicep` — see `.github/skills/shared/procedures/resource-filtering.md` for the script contract. The script applies the shared exclusion rules, writes the filtered resource model JSON to stdout, and should be treated as the source of truth for the remaining steps. *(If pwsh or the script is unavailable, see "Fallback: pwsh Unavailable".)* If the script exits non-zero or produces unparseable output, report the error message to the user and stop. Do not proceed with an empty or partial resource list. Also apply any user-specified exclusion filters from Step 2b. If the filtered resource list is empty after all exclusion rules have been applied, stop and present: ``` All discovered resources were excluded by filtering rules. No Bicep templates can be generated. Review the exclusion rules in `.github/skills/shared/procedures/resource-filtering.md` or adjust your resource type filter. ``` Display the filtered resource list: - If the filtered count is **10 or fewer**: display the full table inline with columns: #, Resource, Type, Location, SKU. - If the filtered count **exceeds 10**: print only the count and a resource-type breakdown summary in the chat response. Create `original-request.md` in the output folder (recording the original user request and scope details at the top), then append the full resource table to it. Reference the file in the chat response. ### 5. Check for Large Scope If the filtered resource count exceeds **30**, print a warning that lists unique resource types with counts, then automatically proceed to generate all resources. Templates will be split into modules by category. Do not pause for user confirmation. ### 6. Deep Property Extraction For each discovered resource, extract the **full** resource configuration from Azure. **6a. Extraction method** Prefer running the shared script over manual per-resource extraction: ``` pwsh .github/skills/shared/scripts/Get-AzureResourceModel.ps1 -ResourceGroup -Enrich -Mode bicep -StripReadOnly -OutFile ``` `-Enrich` fetches full resource detail (`az resource show` per resource) and extracts per-resource-type properties using the mappings in `.github/skills/shared/data/azure-property-paths.json` (`mcpTool` preferred, `fallback` CLI command per resource type, plus `armJsonPath`/composite rules for individual properties). `-Mode bicep` also applies the Step 4 filtering rules automatically. **Generation boundary:** Azure responses contain a mix of deployable configuration and computed state. Generate Bicep only from each model resource's `deployableProperties`, plus explicitly preserved deployable top-level values (`location`, `tags`, `sku`, `kind`, and managed identity configuration). Use the raw `properties` bag only for relationship discovery. Never serialize an unreviewed raw `properties` bag into generated Bicep. If `pwsh` or the script is unavailable, see "Fallback: pwsh Unavailable" to enrich and extract properties by hand. After all resources are extracted, print a single batch summary (e.g., `✅ Extracted 34 resources (3 partial, 2 skipped)`). Do not print per-resource progress lines. **6b. Property filtering and secrets detection** The `-StripReadOnly` switch in the Step 6a command removes read-only, computed, and ARM-internal properties (`provisioningState`, `resourceGuid`, `etag`, timestamps, property-level `id`/`name`/`type`, `identity.principalId`, `privateEndpointConnections`, …) and flags secret-bearing properties. The rules live in `.github/skills/shared/data/arm-readonly-properties.json`. If `pwsh` or the script is unavailable, apply the same rules by hand: strip the `alwaysRemoveAnyDepth` names at any depth and the `alwaysRemoveAtRoot` names at the root of each `properties` bag, apply `removePaths`, and never strip `keepPaths` (`identity.type`, `identity.userAssignedIdentities`) or the deployable `sku`, `kind`, `location`, and `tags`. **6c. Handling flagged secrets** The script writes an optional `secrets` array of dotted property paths on each affected resource (see `.github/skills/shared/azure-resource-model.md`). For every flagged path: - Generate a `@secure()` parameter whose `.bicepparam` value uses `readEnvironmentVariable()` — see `.github/skills/shared/bicep-best-practices.md` - Add it to the output summary as a "requires manual configuration" item **6d. Graceful fallback** If a resource-specific tool fails or is unavailable: - Log a note: `⚠️ Could not fully extract () — using list-level information` - Use the properties available from the initial discovery (Step 3) - Mark the resource as "partially extracted" in the output - Do **not** stop execution due to extraction failures ### 7. Analyze Dependencies Analyze extracted properties to identify relationships between resources — both within the scope and to external resources. **7a. Internal relationships (resources within the scope)** Use the `relationships` array already present on each resource in the model produced by `Get-AzureResourceModel.ps1` (`contains`, `connects`, `depends`, `secures` — see `.github/skills/shared/azure-resource-model.md`). These determine module structure and resource ordering in Bicep. *(If pwsh or the script was unavailable in Step 6, see "Fallback: pwsh Unavailable" to detect relationships and their Bicep implications by hand.)* **7b. External dependencies (resources OUTSIDE the scope)** These are resources that the in-scope resources depend on but that live in other resource groups, subscriptions, or tenants. They **cannot** be deployed by the generated Bicep — they need separate coordination. Detect them using the detection patterns and record them in the field shape defined in the "External Dependency Detection" section of `.github/skills/shared/azure-resource-model.md`. The `type` values recorded there drive the dependency templates generated in Step 9. **7c. Present relationship summary** Show two tables: - **Internal Dependencies (N relationships)**: columns Source, Relationship, Target - **External Dependencies (M dependencies)**: columns External Resource, Type, Required Action, Depended On By If external dependencies exist, warn: "⚠️ M external dependencies require out-of-scope changes. See `dependencies/README.md` after generation." ### 8. Generate Bicep Templates and Bicepparam File Generate **all** Bicep files and the `.bicepparam` file in a single pass. Do not wait for user confirmation. **Before writing any files:** - Sanitize the scope name for use as a folder name: replace spaces with hyphens, remove characters not in `[a-zA-Z0-9_\-.]`, and truncate to 64 characters. Use the sanitized name as the output folder name and record the original scope name in the README. - Write all output files to `.//` relative to the workspace root. - If a directory with that name already exists, warn the user and ask whether to overwrite or choose an alternate folder name before writing any files. This overwrite check is the only user confirmation pause permitted during generation. All other steps proceed without confirmation. Use `.github/skills/shared/azure-resource-configs.md` for per-resource defaults and `.github/skills/shared/bicep-best-practices.md` for generation rules. Use the Tool Preflight capabilities to validate uncertain resource schemas and API versions. **Output structure:** ``` / ├── README.md # Summary: verification results, file list, deploy commands, next steps ├── main.bicep # Entry point — orchestrates all modules ├── .bicepparam # User-editable parameter values with comments ├── modules/ │ ├── networking.bicep # VNets, subnets, NSGs, private endpoints, NICs │ ├── compute.bicep # VMs, App Services, Container Apps, Function Apps │ ├── data.bicep # SQL, Cosmos DB, Storage Accounts, Key Vault, Redis │ ├── identity.bicep # User-assigned managed identities │ ├── monitoring.bicep # Log Analytics, Application Insights, action groups │ └── other.bicep # Resources not mapping to any above category (generated only if needed) └── dependencies/ ├── README.md # Summary of all external dependencies ├── .bicep # Deployable Bicep for each external dependency └── .bicepparam ``` **Bicep generation rules:** Follow the **Template Structure** and **Bicepparam Comment Guidelines** sections of `.github/skills/shared/bicep-best-practices.md` for `main.bicep`, module, and `.bicepparam` structure. The following rules are specific to reverse-engineering a live environment and override the shared defaults: | Area | Rule | |------|------| | Defaults | Match **current Azure values** — the goal is to reproduce the existing environment, not to apply cost-effective sizing. Still enable secure defaults (HTTPS, TLS 1.2, deny public access with PEs) and note any insecure current value with an upgrade comment | | `.bicepparam` comments | Extend the shared comment block with the **current Azure value** for the parameter, alongside 2–3 sizing or tier alternatives with relative cost notes. No hard line limit | | ARM-to-Bicep | Camel-case property names; ARM arrays to Bicep array syntax; `"true"`/`"false"` strings to booleans; inline resource IDs to symbolic refs | ### 9. Generate Out-of-Scope Dependency Bicep Templates For each external dependency from Step 7b, generate a deployable `.bicep` + `.bicepparam` pair in `dependencies/` and document in `dependencies/README.md`. **`dependencies/README.md`**: Summary table (External Resource, Resource Group, Dependency Type, Required Action, Depended On By), links to `.bicep`/`.bicepparam`, per-dependency description with deploy/verify commands, and deployment order instructions. **Per-dependency templates:** | Dependency Type | Bicep Resources | Key Params | |-----------------|----------------|------------| | VNet Peering | Two `virtualNetworkPeerings` resources with `existing` parent VNets | Local/remote VNet names, remote VNet resource ID | | Private DNS Zone | A record + VNet link with `existing` DNS zone | Zone name, record name, IP, VNet resource ID | | Log Analytics | RBAC role assignment on workspace | Workspace name, principal ID, role definition ID | | Key Vault Access | RBAC role assignment on vault | Vault name, principal ID, role definition ID | | External Subnet | Subnet with `existing` parent VNet | VNet name, subnet name, address prefix, delegations | | Container Registry | AcrPull role assignment | Registry name, principal ID | | RBAC Assignment | `Microsoft.Authorization/roleAssignments` | Target resource ID, principal ID, role definition ID | | DNS Zone | `existing` DNS zone with CNAME or A record | Zone name, record name, value, TTL, record type | | Hub Route Table | `existing` route table with routes | Route table name, route name, address prefix, next-hop IP/type | | Any other type | Stub `.bicep` with a comment block explaining the required manual action; no deployable resources | See comment in stub file | Each template: `targetScope = 'resourceGroup'`, top-of-file comment explaining the dependency, `existing` blocks for parents, follows all Bicep best practices, outputs key resource ID. Only generate templates for detected dependencies. ### 10. Validate Generated Bicep Run the **full verification ruleset** from `.github/skills/shared/azure-deployment-verification.md`. This is mandatory — do not skip. Check all rule categories: SKU dependencies, resource compatibility, networking, security, regional availability, version currency, Bicep best practices, missing dependencies, and parameter completeness. Present results using the shared verification output format. Auto-fix errors where possible. Do not present code with known errors. If errors remain after auto-fix attempts, halt delivery of the affected files, present the specific errors to the user with remediation suggestions, and ask whether to proceed with the warnings-only files or stop entirely. ### 11. Write README and Present Output Summary Write a `README.md` to the output root directory (alongside `main.bicep`) containing: - **Source** (resource group, subscription) - **Generated date** - **Pre-deployment verification results** (pass/warning/error counts and details) - **Generated Files** table (file path + description for every generated file) - **Resource counts** (full/partial extraction, excluded) - **External dependency count** and secret count - **Deployment commands** (`az deployment group create` and `New-AzResourceGroupDeployment` examples) - **Next Steps** section pointing to `dependencies/README.md`, post-deploy RBAC steps, DNS verification, and related skills (azv-bicep-whatif, azv-azure-to-diagram, azv-bicep-policy-check) After writing the README, present the same summary in the chat response. ### 12. Clean Up Intermediate Files Delete all intermediate extraction files from the output folder. These were used during discovery and property extraction but are not deliverables: - `extract-*.json` — per-resource CLI output - `resource-list-raw.json` — initial resource list - Temporary resource model JSON file — structured resource model used during generation only; delete it before finishing because its content is captured in the Bicep templates and README Only final deliverables should remain: `main.bicep`, `.bicepparam`, `modules/`, `dependencies/`, `README.md`, and `original-request.md`. ## Important Notes - This skill operates **independently** — no diagram or prior AzVerify output required - `.bicepparam` defaults to **current Azure values** — deploying recreates the same resources - External dependencies are standalone `.bicep`/`.bicepparam` pairs in `dependencies/` - All files generated in a **single pass** — no intermediate confirmation