Microsoft Tech Community - Latest Blogs - Azure Tools Blog

Azure Verified Modules (AVM) is now owned by Azure engineering

jtracey93msft — Tue, 13 Oct 2026 07:52:59 PDT

Azure Verified Modules (AVM) has moved into the Azure Deployments team, inside Microsoft’s Azure engineering organization. That is the headline, and it is a big one for us.

AVM started as a community-led project inside Microsoft, built and maintained largely by people who cared about it alongside their day jobs in various roles and teams across Microsoft. It is now owned by an engineering team, with dedicated engineers working on it every day; as well as those who helped make AVM what it is today.

I want to be clear about what that does and does not mean, because I know the questions this raises. AVM is still open source. The repositories, specifications, the contribution model and the way you consume modules from the public registries are all unchanged. What has changed is the level of investment behind it, and how sustainable we can make it.

In short: Microsoft has increased its investment in AVM. It has moved from a community-led project into Azure engineering, with dedicated engineering resources behind it. It stays open-source. On the back of that, we are updating the support statement and introducing a three-tier module ownership model at the start of 2027 (more on these below).

This blog post has a lot of content, please take the time to read it all but feel free to use the table of contents below to help you navigate it.

If AVM is new to you
What the move lets us fix: our support statement
Introducing module tiering
Why we are not publishing the module tiering list yet
Distributed ownership is still the point
Come and meet the team (AVM Community Call)
What happens next
And finally, thank you to everyone who built this

If AVM is new to you

AVM is the Microsoft standard for Infrastructure as Code (IaC) modules for Azure, in both Bicep and Terraform. Every module is built to the same published specification, passes the same continuous integration (CI) tests, and is published to the official public Bicep and Terraform registries. The idea is simple: you should not have to write the same Azure IaC code again, and you should be able to trust what you pick up.

There is a lot more detail at aka.ms/AVM. And if you would rather watch than read, Jared Holgate and I covered AVM in our recent Azure Infra Summit session: watch the recording on YouTube.

What the move lets us fix: our support statement

Today, the AVM support statement includes day-based targets for responses and fixes. We have not met them consistently, and that does not give you clear or reliable expectations.

We are removing those targets and aligning with the support model used by Azure CLI, Azure PowerShell, Bicep, AzAPI, and the AzureRM Terraform provider.

The move into Azure engineering is the important part. Dedicated engineers will maintain modules directly and improve the tooling, automation, and framework used by all module owners. That is a stronger commitment than any fixed target we cannot reliably meet.

It also lets us be clearer about who maintains each module. Right now, every AVM module is treated identically, and that is not sustainable. So, we are introducing module tiering.

Introducing module tiering

Right now, every AVM module is treated identically. That is not sustainable. A resource group module needs almost no attention. A storage account or virtual machine module needs constant work as the underlying service evolves.

So, today we are introducing two tiers (and thinking about a third) based on who owns and maintains a module:

Tier	Owned by	What it means
Tier 1 (Core)	The AVM engineering team	Modules are owned directly by the AVM team inside Azure engineering. These are the ones we maintain as our day job alongside the AVM specifications and framework
Tier 2 (Maintained)	Any Microsoft employee (FTE)	Modules are owned by any Microsoft full-time employee or team/s. It also includes other Azure engineering teams owning the modules for their own services. This is the model we have today, and it is not going away.
Tier 3 (Open-Source) * being considered for future *	Vetted external owners (future)	An idea, not a commitment. It would let trusted external parties such as Microsoft MVPs and accredited partners own modules. We will not look at this until the 2nd half of calendar year 2027.

Tier

Owned by

What it means

Tier 1
(Core)

The AVM engineering team

Modules are owned directly by the AVM team inside Azure engineering. These are the ones we maintain as our day job alongside the AVM specifications and framework

Tier 2
(Maintained)

Any Microsoft employee (FTE)

Modules are owned by any Microsoft full-time employee or team/s. It also includes other Azure engineering teams owning the modules for their own services.

This is the model we have today, and it is not going away.

Tier 3
(Open-Source)
* being considered for future *

Vetted external owners (future)

An idea, not a commitment. It would let trusted external parties such as Microsoft MVPs and accredited partners own modules. We will not look at this until the 2nd half of calendar year 2027.

One thing that will not change: the bar. Every module in every tier is built to the same AVM specification and passes the same CI checks. Tiering describes who is behind a module, not its quality.

Ownership also stays aligned across languages if in Tier 1. If we own a module in Tier 1, we own it in both Bicep and Terraform.

Why we are not publishing the module tiering list yet

We want to know our real maintenance capacity before we commit. We are spending the rest of 2026 reducing toil and clearing the backlog. This work will show how many modules we can maintain.

We would rather publish a list that we can sustain than change it soon after publication. Publishing a list will also focus attention on excluded modules. We want clear evidence before those discussions start.

For context, our draft puts about 50 resource modules in Tier 1, across Bicep and Terraform. Current telemetry suggests these modules represent about 85 percent of AVM module deployments.

Usage is one input. Critical services and other factors also matter. We will validate the draft before making a public commitment.

Distributed ownership is still the point

AVM has always run on decentralized ownership and moving into engineering does not change that. If anything, it should help. Being inside Azure engineering puts us much closer to the product teams who build the services, and getting more of those teams to own the modules for their own service has been a goal from day one.

That is already happening. With the recent transition of Azure Landing Zones (ALZ), the Azure Migrate team now maintain the ALZ modules and the subscription vending modules in AVM. Those sit in Tier 2, but they are maintained by a dedicated engineering team. Tier 2 is not a lesser tier, it is a broader one.

However, if they currently own a resource module that will be included in Tier 1, they are still welcome to be involved in its ownership alongside the AVM engineering team, but we would also encourage them to own a module outside of Tier 1 so we have an owner on as many modules as possible. But all of this will be dealt with when we implement the tiering structure in early 2027.

Tier 2 ownership remains open to Microsoft employees and teams. The AVM engineering team will support those owners through improved tooling, automation, and the AVM framework. We will confirm ownership changes when we implement module tiering in early 2027.

Come and meet the team (AVM Community Call)

Rather than list names on a page, we would rather you meet the people. Join our next AVM community call, where the new engineering team looking after AVM will introduce themselves and take your questions. If you want to know who is behind AVM now, or discuss anything in this post, this will be the place to do it, and we can’t wait to see you all there!

Next community call: Monday 26th October 2026 @ 16:00 UK | 12:00 EDT | 09:00 PDT | 21:30 IST | 03:00 AEDT

This call will be streamed to YouTube live so use the "Set reminder" / "Notify Me" options on YouTube and also put an entry in your calendar to remind you. This means it will automatically be recorded and published live once finished as well 👍

YouTube Live Link: aka.ms/AVM/CommunityCall

GitHub Issue Link: AVM Community Call - October 2026 · Issue #3079 · Azure/Azure-Verified-Modules - please add a comment for any topics or discussions you'd like covered

Everyone is welcome whether you contribute to AVM or just use it. We want to welcome you for an insight into our roadmap over the next 6 months as well as an open discussion with you all.

What happens next

We update the published module support statement and remove the day-based response targets.
The team keeps burning down issues and pull requests and keeps reducing the manual toil in our CI.
We validate our maintenance run rate through the end of calendar year 2026.
We publish the initial tier classifications once we can stand behind them.
We revisit Tier 3, including the legal and intellectual property questions, in 2027.

AVM got here because customers, partners and contributors backed it and used it in anger. That has not changed, and neither has our need for your input. If you think we are getting this wrong, tell us in GitHub Discussions. Candidly, the feedback we get on this will shape how we land it.

And finally, thank you to everyone who built this

AVM exists because many people put real work into it, often alongside their day jobs. Matt White, Charlie Grabiaud, Mate Barabas, Pankaj Meshram, were some of AVM’s key founders and helped shape the project during its early days that are no longer involved in AVM day-to-day. Jared Holgate, Alexander Sehr, Erika Gressi, Kris Baranek, Sebastian Graf, Rene Hezser and Chris Sidebotham remain involved today helping develop and maintain the AVM framework and specifications with the engineering team.

Some contributors have moved to other roles, teams, or companies. Many continue through issues, pull requests, community calls, and module ownership and contributions. Every contribution helped AVM reach this point and continue to drive it forward today.

The move into Azure engineering adds dedicated investment. It does not replace the community that built and sustained AVM.

To every past and present contributor and module owner: thank you for your time, commitment, and belief in AVM.

Thanks,

Jack and the AVM team.

Azure CLI on macOS got security upgrade: native broker authentication

Alex-wdy — Thu, 8 Oct 2026 21:40:50 PDT

Why we built this

If you manage Azure resources from a Mac today, az login opens a browser tab, you sign in, and a token comes back to the CLI. That's worked well for a long time. As security requirements become more stringent, many enterprise organizations are adopting secure authentication brokers to strengthen identity protection and reduce authentication-related risks.

Many organizations require broker-based authentication as a matter of security policy. A broker is the operating system's own credential broker — on Windows this is the Web Account Manager (WAM), and it's what lets az login reuse your existing signed-in Windows account instead of opening a browser every time. Depending on the broker, device configuration, and policies applied by the organization, broker-based authentication can provide:

Device-bound refresh tokens, which help protect tokens from exfiltration and misuse

Support for Conditional Access and device compliance checks where those capabilities are configured and available

Single sign-on using accounts known to the operating system, reducing repeated credential prompts

Azure CLI has supported broker authentication on Windows for a while. Beginning with Azure CLI 2.91.0, organizations with stringent security requirements can also use broker-based authentication with Azure CLI on macOS.

What changed

Beginning with Azure CLI 2.91.0, broker-based authentication is available in preview on macOS. The feature uses MSAL's native macOS broker support and is disabled by default, so you remain in control of when to enable it.

After you opt in and run az login, Azure CLI opens a native macOS account picker instead of starting the sign-in flow in a browser. You can select an account already known to the broker or add another account. If a compatible broker isn't available, Azure CLI falls back to the existing browser-based sign-in flow.

How Homebrew Cask supports broker authentication

The core MSAL library is open source, but the macOS broker runtime is not. It is subject to strict internal compliance and intellectual property protection requirements and must also satisfy Apple-specific requirements such as notarization.

Azure CLI is now available through Homebrew Cask, a supported installation method that can accommodate these requirements and support broker-based authentication on macOS. The familiar package name continues to work for new installations:

brew update 
brew install azure-cli

You can also select the Cask explicitly:

brew update 
brew install --cask azure-cli

We tested the migration on a Mac that had Azure CLI 2.90.0 installed through the former Homebrew Formula. After brew update, Homebrew detected that azure-cli had moved to homebrew/cask, unlinked the existing Formula, downloaded Azure CLI 2.91.0 or later, and linked the az executable and shell completions from the Cask. The final output confirmed:

azure-cli was successfully installed!
azure-cli has been moved to homebrew/cask.
The existing keg has been unlinked.

Homebrew detects the package migration, installs Azure CLI from Cask, and preserves the az command.

Homebrew also recommended removing the old Formula record when convenient:

brew uninstall --formula --force azure-cli

This means scripts that use brew install azure-cli can continue to use the same package name. If you previously used the Azure CLI preview tap and Homebrew still resolves stale Formula metadata, remove that tap and retry:

brew untap azure/azure-cli 
brew update 
brew install azure-cli

What the broker sign-in experience looks like

Install Azure CLI 2.91.0 or later and make sure a compatible authentication broker, such as Microsoft Company Portal, is available on your Mac.
Enable broker-based authentication:

az config set core.enable_broker_on_mac=true 
az account clear

You can confirm the setting with:

az config get core.enable_broker_on_mac

3. Start a new sign-in:

az login

4. Azure CLI opens the native single sign-on account picker. Select an existing account and choose Continue or use the add-account button to sign in with another account.

After broker authentication is enabled, az login opens the native account picker instead of starting in a browser.

5. Run az account show to confirm that you're signed in with the expected account and tenant.

The broker changes how Azure CLI acquires credentials; it doesn't change Azure CLI's subscription or tenant selection model. If your account belongs to multiple tenants, you might still need to select the intended tenant explicitly:

az login --tenant <tenant-id>

To opt out and return to browser-based authentication:

az account clear 
az config set core.enable_broker_on_mac=false 
az login

If a compatible broker isn't installed or available, Azure CLI automatically falls back to browser-based authentication.

What's next

This is one part of a broader push to bring Azure CLI's macOS experience up to parity with Windows and Linux — including packaging improvements (to keep pace with Apple's tightening notarization requirements). If you run Azure CLI on macOS in an enterprise environment, we'd love to hear from you — file feedback or ask questions at Azure/azure-cli on GitHub.

References

Install Azure CLI on macOS

Azure CLI issues on GitHub

Azure AD Graph API retirement: action required for older versions of Azure CLI and Azure PowerShell

Alex-wdy — Mon, 5 Oct 2026 15:25:40 PDT

Summary

Azure AD Graph API (the legacy graph.windows.net API, not to be confused with Microsoft Graph) entered its retirement process in September 2024, with the general shutdown completed on July 1, 2025. Azure CLI and Azure PowerShell completed their migration away from Azure AD Graph well ahead of that deadline. az ad and the Az module's Microsoft Entra ID (Azure AD) cmdlets have been backed by Microsoft Graph for some time now. If you're running a current version of Azure CLI or Azure PowerShell, no action is required on your part for this specific retirement.

Because Azure CLI and Azure PowerShell are Microsoft first-party clients, their Azure AD Graph application identities have remained available temporarily to provide a transition path for legacy releases that still call Azure AD Graph. However, those legacy releases have long been out of maintenance and are no longer supported; the temporary availability of the application identities does not mean the old releases remain supported.

Beginning after October 6, 2026, the Microsoft Entra team will progressively disable this remaining legacy access over a two-month buffer period. Users of current versions are not affected, but anyone still running an old release should upgrade now. This post explains what changed, why, and how to confirm you're unaffected.

Terminology

This post uses the following terms:

Azure AD Graph API (https://graph.windows.net) — the legacy, now-retired API for reading and writing Microsoft Entra ID (formerly Azure Active Directory) objects: users, groups, applications, service principals, and directory roles.
Microsoft Graph (https://graph.microsoft.com) — Microsoft's current, unified API surface for Entra ID and the broader Microsoft 365 ecosystem, and the only supported path going forward for any identity/directory operation.

If your Azure CLI or Azure PowerShell still uses legacy Azure AD Graph, migrate as soon as possible

Azure CLI has used Microsoft Graph for az ad commands since version 2.37.0, and the identity-related cmdlets in Azure PowerShell have used Microsoft Graph since Az.Resources version 5.1.0. These migrations were completed years before the Azure AD Graph retirement.

Azure CLI releases earlier than 2.37.0 and Az.Resources releases earlier than 5.1.0 have long been out of maintenance and are no longer supported. The temporary availability of the tools' first-party Azure AD Graph application identities was retained only to provide a transition path for those legacy releases; it does not mean that the releases are maintained or supported.

We are notifying users who still use legacy Azure AD Graph versions

We are sending notifications in phases to tenants where telemetry indicates that calls may still be reaching Azure AD Graph endpoints. Some of this traffic comes from legacy Azure CLI or Azure PowerShell releases using the tools' temporarily retained first-party Azure AD Graph identities; other cases typically trace back to one of the following:

An old, unsupported version of Azure CLI or the Az/AzureAD/MSOnline PowerShell modules still in use (for example, pinned in a long-lived CI/CD image or automation runbook that hadn't been updated).
Custom scripts or tooling calling the legacy graph.windows.net endpoint directly via Invoke-RestMethod/curl/a hand-rolled SDK client, independent of az/Az entirely.
The standalone legacy AzureAD or MSOnline PowerShell modules (distinct from the Az module), which were already deprecated separately from this effort and have their own migration path to Microsoft.Graph PowerShell cmdlets.

These notifications are intended to help close out any remaining migration gaps and continue the original retirement communication. Beginning after October 6, 2026, the Microsoft Entra team will progressively disable the remaining legacy first-party access over a two-month buffer period. Old Azure CLI or Azure PowerShell releases that still depend on Azure AD Graph may stop working at any point during this phased shutdown.

How to check whether your automation still uses Azure AD Graph

Checking the version actually running in each environment is the most reliable way to identify legacy Azure CLI or Azure PowerShell usage. Check developer machines as well as CI/CD agents, automation runbooks, scheduled jobs, and container images, which often remain pinned to an older version after interactive environments have been updated.

You may need to work with your tenant, subscription, infrastructure, or automation administrators to locate the system that is generating the legacy traffic. The source may be a developer machine, VM, self-hosted build agent, automation worker, scheduled task, or container host that you do not manage directly. Use the tenant information from any targeted notification together with your organization's sign-in logs, automation inventory, pipeline logs, and VM or container inventory to identify the execution environment, then upgrade it or stop the obsolete job.

Azure CLI

Run the following command in the same environment and execution account used by your automation:

az version

Azure CLI 2.37.0 replaced the Azure AD Graph implementation used by az ad with Microsoft Graph. If the reported version is lower than 2.37.0, upgrade to the latest Azure CLI release and test your scripts before the phased shutdown begins. Also check pipeline definitions, package installation steps, and container image tags for an explicitly pinned Azure CLI version; checking only the version on your local workstation does not verify the version used by automation.

For installations that support the built-in updater, run:

az upgrade

Otherwise, update Azure CLI through the same package manager or installation method originally used, then run the version check again.

After upgrading, review the documented Microsoft Graph migration changes because some command arguments, behavior, and output properties changed. For example, Microsoft Graph directory object output uses id, while the corresponding Azure AD Graph property was objectId. This can affect scripts that parse command output. If you encounter a problem after upgrading, report it in the Azure CLI GitHub repository and include the output of az version, the affected command, and a minimal reproduction with secrets removed.

Azure PowerShell

The Entra ID cmdlets discussed in this post are provided by Az.Resources, so check that module's version rather than relying only on the version of PowerShell itself:

Get-Module Az.Resources -ListAvailable | Sort-Object Version -Descending | Select-Object -First 1 Name, Version, Path

Az.Resources 5.1.0 introduced the Microsoft Graph implementation for the identity-related cmdlets. If the reported version is lower than 5.1.0, update to the latest Az module, restart the PowerShell session, and test your scripts. Check automation accounts, hosted agents, module caches, and container images separately. Also look for scripts that load a specific old version with Import-Module Az.Resources -RequiredVersion or declare a fixed module version in #Requires.

If Az was installed from the PowerShell Gallery, update it with:

Update-Module -Name Az -Force

Restart PowerShell after the update so that the session does not continue using an older module already loaded in memory.

To confirm which module version provides a cmdlet in the current session, run:

(Get-Command Get-AzADUser).Module | Select-Object Name, Version, Path

After upgrading, review the documented Azure PowerShell migration changes because parameter names, input and output types, and object properties changed. If you encounter a problem after upgrading, report it in the Azure PowerShell GitHub repository and include the Az.Resources version, PowerShell version, affected cmdlet, and a minimal reproduction with secrets removed.

Check for direct endpoint calls

Tool versions do not identify custom code that bypasses az ad or the Az cmdlets. Search your repositories, pipeline definitions, runbooks, and configuration files for graph.windows.net. Pay particular attention to calls made through az rest, curl, Invoke-RestMethod, or custom HTTP and SDK clients. Any direct call to that host must be migrated to Microsoft Graph regardless of the installed Azure CLI or Azure PowerShell version.

If you need help upgrading, locating the source of Azure AD Graph traffic, or troubleshooting an issue related to the retirement, you can ask a question in the Azure CLI GitHub repository or the Azure PowerShell GitHub repository, as appropriate. Include the available version information, affected command or cmdlet, execution environment, error message, and a minimal reproduction or relevant logs with all secrets and personal or tenant-sensitive information removed. The Azure CLI and Azure PowerShell teams can then help you investigate and provide guidance.

What you should do

Make sure you're on a current, supported version of Azure CLI or Azure PowerShell. Run the checks above and update if you're on an old release. Do not rely on the two-month buffer period: legacy access will be progressively disabled after October 6, 2026, so an old release may stop working before the end of that period.
If you use the standalone legacy AzureAD or MSOnline PowerShell modules, these are a separate deprecation track from Az and need their own migration to the Microsoft.Graph PowerShell SDK. This is not something updating the Az module alone resolves — see the dedicated migration guidance referenced below.
If you have custom code or scripts calling graph.windows.net directly, those calls will fail outright post-retirement regardless of what version of Azure CLI/PowerShell you run, since this isn't a CLI/PowerShell-specific concern — it's any direct caller of the retired endpoint. Migrate those calls to the Microsoft Graph SDK/API directly.
If you received a targeted notification referencing a specific tenant ID, that means telemetry showed residual traffic from that tenant specifically — check any automation, scheduled scripts, or older images/containers associated with that tenant for one of the causes above.

References

Introducing bicep docs: generate documentation from your Bicep modules

jaredfholgate — Thu, 24 Sep 2026 12:55:33 PDT

TL;DR: The Bicep CLI has a new experimental command, bicep docs generate. Point it at a Bicep module and it writes a README.md next to it that describes the module's resources, parameters, types, outputs and usage examples, all read straight from your code. You can change the layout with your own templates, add details that aren't in the code, and document every module in a repository with one command. It's available now in Bicep CLI v0.47.16 and later.

bicep docs generate ./main.bicep

Why we built it

Module documentation has a habit of drifting away from the code it describes. Someone renames a parameter, adds an output or changes an allowed value, and the README quietly goes out of date. Teams that publish a lot of modules often end up writing their own scripts to keep the two in step.

bicep docs moves that job into the Bicep CLI. It compiles your module and uses the compiler's own understanding of it, so it picks up the details Bicep already knows: metadata, @description decorators, default values, allowed values, length limits, user-defined types, exported types, variables and functions, outputs, and the local modules it references. Run it again whenever the module changes, and the documentation will match the code.

Get started

You need Bicep CLI v0.47.16 or later. Check your version with bicep --version, and see Install Bicep tools if you need to upgrade. There's no feature flag to turn on.

Here's a small storage account module:

metadata name = 'Storage Account'
metadata description = 'Deploys a storage account with secure defaults.'

@description('Required. The name of the storage account. Must be globally unique.')
@minLength(3)
@maxLength(24)
param name string

@description('Optional. The Azure region to deploy the storage account to.')
param location string = resourceGroup().location

@description('Optional. The storage account SKU.')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
])
param skuName string = 'Standard_LRS'

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: name
  location: location
  kind: 'StorageV2'
  sku: {
    name: skuName
  }
  properties: {
    allowBlobPublicAccess: false
    minimumTlsVersion: 'TLS1_2'
  }
}

@description('The resource ID of the storage account.')
output resourceId string = storageAccount.id

Generate its documentation:

bicep docs generate ./modules/storage-account/main.bicep

Bicep writes README.md next to main.bicep. For this module, the built-in layout includes a list of sections, the resource types, a usage example (more on those below), the parameters with the details of each one, and the outputs. When a module has them, it also covers exported types, variables and functions, and referenced modules. Here's an excerpt:

# Storage Account

Deploys a storage account with secure defaults.

## Parameters

| Name | Type | Required | Description |
| :-- | :-- | :-- | :-- |
| `location` | `string` | No | Optional. The Azure region to deploy the storage account to. |
| `name` | `string` | Yes | Required. The name of the storage account. Must be globally unique. |
| `skuName` | `string` | No | Optional. The storage account SKU. |

### `location`

- Default value: `resourceGroup().location`

### `name`

- Min length: 3

- Max length: 24

### `skuName`

- Default value: `'Standard_LRS'`

- Allowed values: `Standard_GRS`, `Standard_LRS`, `Standard_ZRS`

A couple of options you'll use often:

--stdout prints the result to the terminal instead of writing a file, which is handy for a quick preview.
--outfile writes to a file of your choice, and --outdir writes the documentation into another folder.

Because the command is experimental, Bicep prints a warning each time you run it.

Usage examples are included automatically

Examples are often the most useful part of module documentation, so bicep docs looks for them next to your module. By default it picks up:

.bicep files in an examples folder, and main.bicep files in its subfolders
*.test.bicep files anywhere under a tests folder

Files named dependencies*.bicep are skipped. Each example's heading comes from its metadata name. Without one, Bicep uses the name of the folder the example is in, or its file name if it's not in a subfolder. The description comes from metadata description, or else the // comments at the top of the file. For example, this file in modules/storage-account/examples becomes a "Zone-redundant storage account" example in the README:

metadata name = 'Zone-redundant storage account'
metadata description = 'Deploys a storage account that keeps copies of your data in three availability zones.'

module storageAccount '../main.bicep' = {
  params: {
    name: 'stdocsdemo001'
    skuName: 'Standard_ZRS'
  }
}

If your examples live somewhere else, list their locations in documentation.examples.sources in bicepconfig.json. Your list replaces the default locations.

Make it your own with templates

The built-in layout is a good start, but you'll probably have your own conventions. bicep docs renders documentation with Scriban, a lightweight text templating language. Write a template, then point to it from bicepconfig.json:

{
  "documentation": {
    "template": {
      "file": "templates/readme.scriban"
    }
  }
}

The template path is relative to the bicepconfig.json file. As with its other settings, Bicep uses the bicepconfig.json nearest to each module.

This template writes a parameters table and an outputs table:

# {{ module.name }}

{{ module.description }}

## Parameters

| Name | Type | Required | Description |
| :-- | :-- | :-- | :-- |
{{~ for parameter in module.parameters ~}}
| `{{ parameter.name }}` | `{{ parameter.type }}` | {{ if parameter.required }}Yes{{ else }}No{{ end }} | {{ parameter.description }} |
{{~ end ~}}

## Outputs

| Name | Type | Description |
| :-- | :-- | :-- |
{{~ for output in module.outputs ~}}
| `{{ output.name }}` | `{{ output.type }}` | {{ output.description }} |
{{~ end ~}}

The ~ inside the braces removes the spaces and line breaks next to a tag, so the loops don't add blank lines that would break the tables. Your template receives a module object with the module's name, description, targetScope, resourceTypes, parameters, exportedTypes, exportedVariables, exportedFunctions, outputs, references and usageExamples. The command documentation lists every field.

A couple of tips:

Split a big template into smaller files with Scriban's include, and set documentation.template.includeRoot to the folder that holds them.
The built-in Markdown template is a Scriban template too, so it's a good place to start.

Add details that aren't in your code

Some information doesn't belong in Bicep, such as the team that owns a module, where to get support, or the module's version. Pass it in as custom values and use them in your template as custom.<key>:

**Owner:** {{ custom.owner }} | **Version:** {{ custom.version }} | [Get support]({{ custom.supportUrl }})

Supply values one at a time with --custom-template-value, or load several from a JSON file with --custom-template-value-file-path:

bicep docs generate ./modules/storage-account/main.bicep `
    --custom-template-value owner="Platform Team" `
    --custom-template-value-file-path ./docs-values.json

Where docs-values.json contains:

{
  "supportUrl": "https://contoso.example/support",
  "version": "1.0.0"
}

Both options can be repeated. If the same key is set more than once, the last one on the command line wins.

Go beyond Markdown

Scriban writes whatever text your template contains, so the output doesn't have to be Markdown. A template could produce JSON for a module catalogue, HTML for an internal portal, or input for another tool. This template produces JSON, and Scriban's object.to_json function takes care of quotes and escaping:

{
  "name": {{ module.name | object.to_json }},
  "description": {{ module.description | object.to_json }},
  "parameters": [
{{~ for parameter in module.parameters ~}}
    {
      "name": {{ parameter.name | object.to_json }},
      "type": {{ parameter.type | object.to_json }},
      "required": {{ parameter.required | object.to_json }}
    }{{ if !for.last }},{{ end }}
{{~ end ~}}
  ]
}

Set documentation.template.file to this template, then use --outfile to save the result with a .json file name:

bicep docs generate ./modules/storage-account/main.bicep --outfile ./modules/storage-account/module.json

To change the default file name for every module instead, set documentation.output.file in bicepconfig.json.

Each module uses the one template set in its nearest bicepconfig.json. To get both Markdown and JSON from the same modules, make that template a small switch that includes the right template based on a custom value:

{{~ if custom.format == "json" ~}}
{{~ include "catalog.scriban" ~}}
{{~ else ~}}
{{~ include "readme.scriban" ~}}
{{~ end ~}}

Set documentation.template.includeRoot to the folder that holds the templates. Then run the command as normal for the README, and add --custom-template-value format=json --outfile ./modules/storage-account/module.json for the JSON.

Document every module in one go

Use --pattern to document every module that matches a wildcard:

bicep docs generate --pattern './modules/**/main.bicep'

Each module gets its own README.md next to its main.bicep. Add --outdir ./docs to put them in a separate folder instead, and Bicep recreates the folder structure beneath it. If a module has compile errors, Bicep reports them, carries on documenting the other modules, and returns exit code 1 at the end.

To see this at scale, the demo repository generates Azure Verified Modules (AVM) style documentation for 20 App Service modules, including their child modules, with a single command. Its template works out each module's registry reference and main resource type from the module itself. The AVM team is standardising and consolidating its tooling, and bicep docs is part of that work.

Keep documentation up to date in CI

Because the documentation comes from the code, your pipeline can check that it's current. Regenerate it, then fail the build if anything changed:

bicep docs generate --pattern './modules/**/main.bicep'
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

$changes = git status --porcelain
if ($changes) {
    $changes
    throw 'Module documentation is out of date. Run bicep docs generate and commit the result.'
}

The generated documentation is only as good as your descriptions, so the new description linter rules in Bicep v0.47 make a good partner. They're off by default and flag missing or empty @description decorators. Turn on the ones you need in bicepconfig.json:

{
  "analyzers": {
    "core": {
      "rules": {
        "use-description-params": { "level": "warning" },
        "use-description-outputs": { "level": "warning" },
        "use-description-types": { "level": "warning" },
        "use-description-type-properties": { "level": "warning" }
      }
    }
  }
}

There's also use-description-vars for variables. Thanks to @johnlokerse for contributing these rules!

Building tools on top of Bicep?

The same generator is available through the Bicep CLI's JSON-RPC interface as bicep/generateDocs. It returns the rendered text and leaves writing files to you. For .NET, the Azure.Bicep.RpcClient package wraps it.

It's experimental, and we'd love your feedback

bicep docs is experimental. The command options, configuration, template model and built-in layout may change between releases without a breaking-change notice.

One change is already on the way. In v0.47 you can also choose a template with the --template-file and --template-root options. The next release removes these options, so templates are set only with documentation.template.file and documentation.template.includeRoot in bicepconfig.json. The examples in this post already use bicepconfig.json, so they'll keep working.

Try it on your own modules and tell us what works and what's missing by opening an issue in the Bicep repository.

Learn more

bicep docs command documentation
Demo repository, with step-by-step demos from the built-in layout to AVM-style documentation
Bicep v0.47.16 release notes
Scriban language reference
bicep docs is also featured in the September 2026 Bicep community call. Community call recordings are on the Azure Deployments & Governance YouTube channel, and you can sign up to join future calls.

Azure Key Vault Control Plane API Update: Required Upgrade for Azure CLI and Azure PowerShell Users

Alex-wdy — Tue, 1 Sep 2026 23:16:45 PDT

Deadline: February 27, 2027

All Azure Key Vault control plane (management) API versions released before 2026-02-01 will stop working on February 27, 2027.

This does NOT affect the data plane (getting/setting secrets, keys, and certificates) — only vault and access-control management operations are impacted.

TL;DR — What you need to do

Upgrade Azure CLI to 2.90.0 or later (run az upgrade).
Upgrade Az PowerShell's Az.KeyVault module to 6.6.1 or later, or upgrade the Az package to 16.3.0 or later.
Do this before February 27, 2027 to avoid any interruption to vault management operations.
No data plane changes are required — reading/writing secrets, keys, and certificates is unaffected.
For details, see Prepare for Key Vault API version 2026-02-01 and later.

What is changing

Current releases of Azure CLI 2.90.0 or later and Az PowerShell 16.3.0 or later (including Az.KeyVault 6.6.1 or later) already use Key Vault control plane API version 2026-02-01. Upgrade to these versions before February 27, 2027; after that date, earlier control plane API versions will no longer be served.

Who is affected

You are affected if you use either of the following:

Azure CLI scripts or automation that call az keyvault management commands (create, update, network-rule, access-policy, etc.).
Az PowerShell scripts that use the Az.KeyVault module's management cmdlets (New-AzKeyVault, Set-AzKeyVault, Update-AzKeyVault, etc.).

Minimum versions to upgrade to

Tool / SDK	Minimum version	How to upgrade
Azure CLI	2.90.0 or later	az upgrade
Az PowerShell (Az.KeyVault module)	Az.KeyVault 6.6.1 or later; or Az 16.3.0 or later	Update-Module Az -Force

Impact if you take no action

What breaks on and after February 27, 2027 if you have not upgraded

Key Vault management operations (create/update/delete vault, change network rules, change access policies or RBAC settings, etc.) issued with a pre-2026-02-01 API version will fail.

You’ll get the following error message: “Due to an RBAC security default, Key Vault's Resource Manager API versions older than 2026-02-01 will retire on 2027-04-01.”

Your vaults are NOT deleted and existing secrets/keys/certificates remain fully accessible via the data plane — only management (control plane) operations are blocked.

There is no way to opt out or request an extension once the retirement takes effect on February 27, 2027.

How to check your installed versions

Check your Azure CLI version

Run the following command:

az version

Check the azure-cli value. If the installed version is earlier than 2.90.0, upgrade Azure CLI before February 27, 2027 by running az upgrade.

Check your Az PowerShell version

Run the following commands:

Get-InstalledModule Az, Az.KeyVault | Select-Object Name, Version

If Az.KeyVault is earlier than 6.6.1, or the installed Az package is earlier than 16.3.0, upgrade before February 27, 2027. To upgrade the complete Az package, run:

Update-Module Az -Force

Alternatively, to update only the Az.KeyVault module to the latest version, run:

Update-Module Az.KeyVault -Force

Timeline

Date	Milestone
March 2026	Control plane API version 2026-02-01 generally available across public Azure regions, Azure Government, and Azure operated by 21Vianet.
Today → February 27, 2027	Preparation window. Upgrade to Azure CLI 2.90.0 or later, Az.KeyVault 6.6.1 or later, or Az 16.3.0 or later before February 27, 2027.
February 27, 2027	All control plane API versions released before 2026-02-01 are retired and stop being served.

Questions?

For any questions about Azure CLI or Azure PowerShell, please submit feedback through GitHub:

Microsoft Tech Community - Latest Blogs - Azure Tools Blog

Azure Verified Modules (AVM) is now owned by Azure engineering

Table of Contents

If AVM is new to you

What the move lets us fix: our support statement

Introducing module tiering

Why we are not publishing the module tiering list yet

Distributed ownership is still the point

Come and meet the team (AVM Community Call)

What happens next

And finally, thank you to everyone who built this

Azure CLI on macOS got security upgrade: native broker authentication

Why we built this

What changed

How Homebrew Cask supports broker authentication

What the broker sign-in experience looks like

What's next

References

Azure AD Graph API retirement: action required for older versions of Azure CLI and Azure PowerShell

Summary

Terminology

If your Azure CLI or Azure PowerShell still uses legacy Azure AD Graph, migrate as soon as possible

We are notifying users who still use legacy Azure AD Graph versions

How to check whether your automation still uses Azure AD Graph

Azure CLI

Azure PowerShell

Check for direct endpoint calls

What you should do

References

Introducing bicep docs: generate documentation from your Bicep modules

Why we built it

Get started

Usage examples are included automatically

Make it your own with templates

Add details that aren't in your code

Go beyond Markdown

Document every module in one go

Keep documentation up to date in CI

Building tools on top of Bicep?

It's experimental, and we'd love your feedback

Learn more

Azure Key Vault Control Plane API Update: Required Upgrade for Azure CLI and Azure PowerShell Users

TL;DR — What you need to do

What is changing

Who is affected

Minimum versions to upgrade to

Impact if you take no action

How to check your installed versions

Check your Azure CLI version

Check your Az PowerShell version

Timeline

Questions?