--- name: update-avm-modules description: >- **WORKFLOW SKILL** — Update Azure Verified Modules (AVM) to their latest versions in Bicep files. Scans for AVM module references, queries the Microsoft Container Registry (MCR) for latest versions, compares using semantic versioning, reviews breaking changes, and applies updates with validation. WHEN: 'update AVM', 'update Bicep modules', 'latest AVM versions', 'update Azure Verified Modules', 'upgrade Bicep dependencies', 'check AVM versions', 'update module versions'. INVOKES: run_in_terminal for MCR API queries and bicep lint. FOR SINGLE OPERATIONS: Use az bicep build to validate individual files. metadata: author: plagueho.os version: "1.0" reference: https://github.com/Azure/bicep-registry-modules compatibility: - GitHub Copilot - VS Code - Requires az CLI with Bicep extension - Requires network access to mcr.microsoft.com argument-hint: >- Specify the Bicep file(s) to update (e.g., "infra/main.bicep") or say "all Bicep files" to scan the entire infra/ directory. user-invocable: true enabled: false source: github:PlagueHO/plagueho.skills imported-from: github:PlagueHO/plagueho.skills --- # Update AVM Modules Update Azure Verified Modules (AVM) in Bicep files to their latest published versions. The workflow scans Bicep files for module references, queries the Microsoft Container Registry (MCR) for available versions, identifies updates, reviews breaking changes, applies updates, and validates the result. ## Prerequisites - **Azure CLI** with Bicep extension (`az bicep build` must work). - **Network access** to `mcr.microsoft.com` for version queries. - **PowerShell 7+** (Windows) or **curl + jq** (macOS/Linux) for the version check scripts. ## Process ### Step 1 — Identify Target Files Determine which Bicep files to update: - If the user specified a file, use that file. - If the user said "all", scan `infra/` recursively for `*.bicep` files. - List the files and confirm with the user before proceeding. ### Step 2 — Extract Module References For each target file, extract all AVM module references matching the pattern: ```text br/public:avm/res/{service}/{resource}:{version} br/public:avm/ptn/{pattern}:{version} br/public:avm/utl/{utility}:{version} ``` Build a list of `{ module, currentVersion, filePath, lineNumber }` entries. If no AVM modules are found, inform the user and stop. ### Step 3 — Query Latest Versions Use the version check script to query MCR for the latest version of each unique module. The scripts are in this skill's `scripts/` directory. **PowerShell** (Windows): ```powershell & "/scripts/Get-AvmLatestVersions.ps1" -BicepFile "" ``` **Shell** (macOS/Linux): ```bash "/scripts/get-avm-latest-versions.sh" "" ``` The scripts output a table with columns: `Module`, `Current`, `Latest`, `Status`. If the scripts are unavailable, query the MCR API directly: ```text GET https://mcr.microsoft.com/v2/bicep/{module}/tags/list ``` Parse the `tags` array and sort by semantic versioning to find the latest stable release (exclude pre-release tags containing `-`). ### Step 4 — Compare and Classify For each module, classify the update: | Status | Condition | Icon | |--------|-----------|------| | Current | `current == latest` | ✅ | | Patch update | Major and minor match, patch differs | 🔄 | | Minor update | Major matches, minor differs | 🔄 | | Major update | Major version differs | ⚠️ | | Failed | MCR query failed | ❌ | ### Step 5 — Review Breaking Changes For any **major** or **minor** version updates: 1. Fetch the module changelog/README from GitHub: `https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/{service}/{resource}` 2. Check for incompatible parameter changes, removed parameters, renamed parameters, or behavioral changes. 3. If breaking changes are detected, **PAUSE and present them to the user** before applying. Ask for explicit approval. **Breaking Change Policy** — always pause for approval when updates involve: - Incompatible parameter changes (renamed, removed, type changed) - Security or compliance modifications - Behavioral changes that affect deployment outcomes ### Step 6 — Apply Updates For approved updates, edit each Bicep file to replace the old version with the new version in the module reference: ```bicep // Before module storageAccount 'br/public:avm/res/storage/storage-account:0.9.0' = { // After module storageAccount 'br/public:avm/res/storage/storage-account:0.14.0' = { ``` If breaking changes require parameter adjustments, apply those as well. ### Step 7 — Validate Run Bicep linting to ensure all updated files are valid: ```powershell az bicep build --file ``` If validation fails: 1. Report the specific error. 2. Attempt to fix parameter issues caused by the version change. 3. Re-validate. 4. If still failing, revert that module to its previous version and mark it as ⚠️ in the results. ### Step 8 — Present Results Display a summary table: | Module | Current | Latest | Status | Action | Docs | |--------|---------|--------|--------|--------|------| | `avm/res/storage/storage-account` | 0.9.0 | 0.14.0 | 🔄 | Updated | [📖](https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/storage/storage-account) | | `avm/res/search/search-service` | 0.11.1 | 0.11.1 | ✅ | Current | [📖](https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/search/search-service) | | `avm/res/network/virtual-network` | 0.5.0 | 0.8.0 | ⚠️ | Manual review | [📖](https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/network/virtual-network) | **Status Icons:** - ✅ Current — already on latest version - 🔄 Updated — successfully updated - ⚠️ Manual review required — breaking changes need attention - ❌ Failed — update could not be applied or validated After the table, list any files that were modified and remind the user to run `az bicep build --file infra/main.bicep` for a final end-to-end validation. ## MCR API Reference ### Tags List Endpoint ```text GET https://mcr.microsoft.com/v2/bicep/avm/res/{service}/{resource}/tags/list ``` Returns JSON: ```json { "name": "bicep/avm/res/storage/storage-account", "tags": ["0.6.0", "0.7.0", "0.8.0", "0.9.0", "0.14.0"] } ``` ### Module Path Mapping | Bicep Reference | MCR Path | |----------------|----------| | `br/public:avm/res/storage/storage-account:0.14.0` | `bicep/avm/res/storage/storage-account` | | `br/public:avm/ptn/ai-platform/baseline:0.1.0` | `bicep/avm/ptn/ai-platform/baseline` | ### GitHub Documentation ```text https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/{service}/{resource} ``` ## Edge Cases - **Custom/local modules** (not `br/public:avm/`): Skip — only update AVM registry modules. - **Pre-release tags**: Exclude tags containing `-` (e.g., `0.5.0-preview`). - **Network errors**: If MCR is unreachable, report the error and skip that module rather than failing the entire run. - **Multiple files referencing same module at different versions**: Update all to the same latest version for consistency. ### Step 1 — <!-- Describe the first step. Use imperative form. --> ### Step 2 — <Title> <!-- Describe the next step. --> ## Examples <!-- Provide input/output examples where applicable. --> **Example 1:** Input: <description> Output: <description> ## Additional Edge Cases <!-- Document edge cases and how to handle them. --> - <Edge case description and resolution> ## Validation <!-- How to verify the skill produced a correct result. --> 1. <Verification step>