Introducing bicep docs: generate documentation from your Bicep modules
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.
Building a Fully Automated Azure Landing Zone Deployment Using Azure DevOps and Terraform
Discover how to build a fully automated Azure Landing Zone using Azure DevOps and Terraform. This article walks through real-world Git workflows, CI/CD automation, environment promotion strategies, and governance integration to create secure, scalable, and enterprise-ready Azure environments.From Prompt to Production: Open in VS Code for Terraform in Azure Copilot
We’re excited to introduce a new step in the Terraform on Azure experience: Open in VS Code, now available directly from Azure Copilot in the Azure Portal. This capability helps you move seamlessly from AI‑generated Terraform code to real Azure deployments - within a connected, guided workflow designed for enterprise scenarios. Why This Matters Infrastructure as Code with Terraform is powerful, but moving from generated configuration to a deployed environment typically involves multiple tools and handoffs. Teams need to understand Terraform state, work with remote backends, and integrate their code into version‑controlled CI/CD pipelines - often backed by Terraform Cloud or Azure‑native backends in enterprise environments. Open in VS Code brings these steps together. It bridges the gap between AI‑assisted authoring in the Azure Portal and the real‑world workflows required to validate, manage state, and deploy infrastructure with confidence. Continue Your Workflow in VS Code With Azure Copilot, you can describe your infrastructure in natural language and generate Terraform configurations in seconds. For example: “Create an Azure Container App using Terraform with a managed environment, Log Analytics enabled, and a system‑assigned managed identity to securely pull images from Azure Container Registry.” Copilot generates the Terraform configuration for you. From there, you can select Open full view to enter a full‑screen Terraform editor, and then choose Open in VS Code to launch the configuration in an Azure‑hosted VS Code environment. There’s no need to download files or set up a local development environment. VS Code for the web opens with Azure authentication already configured, along with commonly used extensions, so you can immediately focus on refining, validating, and preparing your infrastructure for deployment. Built‑in Guidance for Real Deployments Beyond editing, the VS Code experience includes built‑in, step‑by‑step guidance to help you deploy your Terraform configuration into your own Azure environment - whether you’re experimenting or preparing for production. Because Terraform relies on state management, the workflow starts by helping you choose and configure a backend. Backend Options Option 1: Azure Storage Account as a remote backend A natural fit for Azure‑native and enterprise environments. The experience guides you through creating or selecting a storage account and configuring Terraform to store state securely in Azure. Option 2: HCP Terraform (Terraform Cloud) as a remote backend Ideal for teams already using Terraform Cloud. The guided flow helps you authenticate, connect to an existing organization and workspace, and generate the required backend configuration directly into your Terraform files. Option 3: Temporary workspace for quick validation Designed for learning and experimentation. You can run terraform plan and terraform apply directly in the Azure workspace with temporary state, without committing to a long‑term backend - ideal for quick validation, but not intended for production use. Each option includes an end‑to‑end walkthrough, so you can complete backend setup and run Terraform commands without leaving the VS Code environment or searching through external documentation. Connecting Code, State, and Deployment This experience connects three essential parts of the Terraform workflow: AI‑assisted code generation in Azure Portal Copilot Interactive editing and guided execution in VS Code for the web Flexible backend options for managing Terraform state Together, these pieces make it easier to move from idea to infrastructure in a structured, supported way—whether you’re new to Terraform or managing production workloads with established CI/CD pipelines. Available Now - and What’s Next The Open in VS Code experience for Terraform is now public preview in Azure Portal Copilot. We’re continuing to invest in this workflow, including clearer deployment guidance, future integration with GitHub Actions and other CI/CD pipelines, and deeper enhancements to the full‑screen Terraform editor experience. If you haven’t tried it yet, generate a Terraform configuration with Azure Copilot and open it in VS Code to go from prompt to production end to end in one connected workflow.Azure Landing Zones Accelerators for Bicep and Terraform. Announcing General Availability!
Azure Landing Zones Accelerators are designed to simplify the process of onboarding your Infrastructure as Code into a robust CI / CD pipeline with Azure DevOps or GitHub. Learn more about what the Accelerator can do for you and why you should be using it.Gaining Confidence with Az CLI and Az PowerShell: Introducing What if & Export Bicep
Ever hesitated before hitting Enter on a command, wondering what changes it might make? You’re not alone. Whether you’re deploying resources or updating configurations, the fear of unintended consequences can slow you down. That’s why we’re introducing new powerful features in Azure CLI and Azure PowerShell to preview the changes the commands may make: the What if and Export Bicep features. These capabilities allow you to preview the impact of your commands and allow you to export them as Bicep templates, all before making any changes to your Azure environment. Think of them as your safety net: you can validate actions, confirm resource changes, and even generate reusable infrastructure-as-code templates with confidence. Currently, these features are in private preview, and we’re excited to share how you can get early access. Why This Matters Reduce risk: Avoid accidental resource deletions or costly misconfigurations. Build confidence: Understand exactly what your command will do before execution. Accelerate adoption of IaC: Convert CLI commands into Bicep templates automatically. Improve productivity: Validate scripts quickly without trial-and-error deployments. How It Works What if preview of commands All you have to do is add the `--what-if` parameter to Azure CLI commands and then the `-DryRun` command to Azure PowerShell commands like below. Azure CLI: az storage account create --name "mystorageaccount" --resource-group "myResourceGroup" --location "eastus" --what-if Azure PowerShell: New-AzVirtualNetwork -name MyVNET -ResourceGroupName MyResourceGroup -Location eastus -AddressPrefix "10.0.0.0/16" -DryRun Exporting commands to Bicep To generate bicep from the command you will have to add the `--export-bicep` command with the --what-if parameter to generate a bicep file. The bicep code will be saved under the `~/.azure/whatif` directory on your machine. The command will specific exactly where the file is saved on your machine. Behind the scenes, AI translates your CLI command into Bicep code, creating a reusable template for future deployments. After generating the Bicep file, the CLI automatically runs a What-If analysis on the Bicep template to show you the expected changes before applying them. Here is a video of it in action! Here is another example where there is delete, modify and create actions happening all together. Private Preview Access These features are available in private preview. To sign up: Visit the aka.ms/PreviewSignupPSCLI Submit your request for access. Once approved, you’ll receive instructions to download the preview package. Supported Commands (Private Preview) Given these features are in a preview we have only added support for a small set of commands for the time being. Here’s a list of commands that will support these features during the private preview: Azure CLI Az vm create Az vm update az storage account create az storage container create az storage share create az network vnet create az network vnet update az storage account network-rule add az vm disk attach az vm disk detach az vm nic remove Azure PowerShell New-AzVM Update-AzVM New-AzStorageAccount New-AzRmStorageShare New-AzRmStorageContainer New-AzVirtualNetwork Set-AzVirtualNetwork Add-AzStorageAccountNetworkRule Next Steps Sign up for the private preview. Install the packages using the upcoming script. Start using --what-if, -DryRun, and --export-bicep to make safer, smarter decisions and accelerate your IaC journey. Give us feedback on what you think of the feature! At https://aka.ms/PreviewFeedbackWhatIf Thanks so much! Steven Bucher PM for Azure Client ToolsAnnouncing MSGraph Provider Public Preview and the Microsoft Terraform VSCode Extension
We are thrilled to announce two exciting developments in the Microsoft ecosystem for Terraform infrastructure-as-code (IaC) practitioners: the public preview of the Terraform Microsoft Graph (MSGraph) provider and the release of the Microsoft Terraform Visual Studio Code (VSCode) extension. These innovations are designed to streamline your workflow, empower your automation, and make managing Microsoft cloud resources easier than ever. Public Preview: Terraform Microsoft Graph (MSGraph) Provider The Terraform MSGraph provider empowers you to manage Entra APIs like privileged identity management as well as M365 Graph APIs like SharePoint sites from day 0 by leveraging the power and flexibility of HashiCorp Configuration Language (HCL) in Terraform. resource "msgraph_resource" "application" { url = "applications" body = { displayName = "My Application" } response_export_values = { all = "@" app_id = "appId" } } output "app_id" { value = msgraph_resource.application.output.app_id } output "all" { // it will output the whole response value = msgraph_resource.application.output.all } Historically, Terraform users could utilize the `azuread` provider to manage Entra features like users, groups, service principals, and applications. The new `msgraph` provider also supports these features and extends functionality to all beta and v1 Microsoft Graph endpoints. Querying role assignments for a service principal The below example shows how to use the `msgraph` provider to grant app permissions to a service principal: locals { MicrosoftGraphAppId = "00000003-0000-0000-c000-000000000000" # AppRoleAssignment userReadAllAppRoleId = one([for role in data.msgraph_resource.servicePrincipal_msgraph.output.all.value[0].appRoles : role.id if role.value == "User.Read.All"]) userReadWriteRoleId = one([for role in data.msgraph_resource.servicePrincipal_msgraph.output.all.value[0].oauth2PermissionScopes : role.id if role.value == "User.ReadWrite"]) # ServicePrincipal MSGraphServicePrincipalId = data.msgraph_resource.servicePrincipal_msgraph.output.all.value[0].id TestApplicationServicePrincipalId = msgraph_resource.servicePrincipal_application.output.all.id } data "msgraph_resource" "servicePrincipal_msgraph" { url = "servicePrincipals" query_parameters = { "$filter" = ["appId eq '${local.MicrosoftGraphAppId}'"] } response_export_values = { all = "@" } } resource "msgraph_resource" "application" { url = "applications" body = { displayName = "My Application" requiredResourceAccess = [ { resourceAppId = local.MicrosoftGraphAppId resourceAccess = [ { id = local.userReadAllAppRoleId type = "Scope" }, { id = local.userReadWriteRoleId type = "Scope" } ] } ] } response_export_values = { appId = "appId" } } resource "msgraph_resource" "servicePrincipal_application" { url = "servicePrincipals" body = { appId = msgraph_resource.application.output.appId } response_export_values = { all = "@" } } resource "msgraph_resource" "appRoleAssignment" { url = "servicePrincipals/${local.MSGraphServicePrincipalId}/appRoleAssignments" body = { appRoleId = local.userReadAllAppRoleId principalId = local.TestApplicationServicePrincipalId resourceId = local.MSGraphServicePrincipalId } } SharePoint & Outlook Notifications With your service principals properly configured, you can set up M365 endpoint workflows such an outlook notification template list as shown below. The actual service principal setup has been omitted from this code sample for the sake of brevity, but you will need Sites.Manage.All, Sites.ReadWrite.All, User.Read, and User.Read.All permissions for this example to work: data "msgraph_resource" "sharepoint_site_by_path" { url = "sites/microsoft.sharepoint.com:/sites/msgraphtest:" response_export_values = { full_response = "@" site_id = "id || ''" } } resource "msgraph_resource" "notification_templates_list" { url = "sites/${msgraph_resource.sharepoint_site_by_path.output.site_id}/lists" body = { displayName = "DevOps Notification Templates" description = "Centrally managed email templates for DevOps automation" template = "genericList" columns = [ { name = "TemplateName" text = { allowMultipleLines = false appendChangesToExistingText = false linesForEditing = 1 maxLength = 255 } }, { name = "Subject" text = { allowMultipleLines = false appendChangesToExistingText = false linesForEditing = 1 maxLength = 500 } }, { name = "HtmlBody" text = { allowMultipleLines = true appendChangesToExistingText = false linesForEditing = 10 maxLength = 10000 } }, { name = "Recipients" text = { allowMultipleLines = true appendChangesToExistingText = false linesForEditing = 3 maxLength = 1000 } }, { name = "TriggerConditions" text = { allowMultipleLines = true appendChangesToExistingText = false linesForEditing = 5 maxLength = 2000 } } ] } response_export_values = { list_id = "id" list_name = "displayName" web_url = "webUrl" } } The MSGraph provider is to AzureAD as the AzAPI provider is to AzureRM. Since support for resource types is automatic, you can access the latest features and functionality as soon as they're released via the provider. AzureAD will continue to serve as the convenience layer implementation of a subset of Entra APIs. We invite you to try the new provider today: - Deploy your first msgraph resources - Check out the registry page - Visit the provider GitHub Introducing the Microsoft Terraform VSCode Extension The new official Microsoft Terraform extension for Visual Studio Code consolidates AzureRM, AzAPI, and MSGraph VSCode support into a single powerful extension. The extension supports exporting Azure resources as Terraform code, as well as IntelliSense, syntax highlighting, and code sample generation. It replaces the Azure Terraform and AzAPI VSCode extensions and adds some new features. Installation & Migration New users can install the extension by searching “Microsoft Terraform” within Visual Studio Marketplace or their “Extensions” tab. Users can also click this link to the Visual Studio marketplace. Users of the “Azure Terraform” extension can navigate to “Extensions” tab and selecting the old extension. Select the “Migrate” button to move to the new extension. Users of the “Terraform AzAPI Provider” extension will be directed to the new extension: New Features Export Azure Resources As Terraform This feature allows you to export existing Azure resources as Terraform configuration blocks using Azure Export for Terraform. This helps you migrate existing Azure resources to Terraform-managed infrastructure. Open the Command Palette (Command+Shift+P on macOS and Ctrl+Shift+P on Windows/Linux). Search for and select the command Microsoft Terraform: Export Azure Resource as Terraform. Follow the prompts to select the Azure subscription and resource group containing the resources you want to export. Select the azurerm provider or the azapi provider to export the resources. The extension will generate the Terraform configuration blocks for the selected resources and display them in a new editor tab. Support for MSGraph The new extension comes fully equipped with intellisense, code completion, and code samples just like the AzAPI provider. See the next section for recorded examples of these features within the AzureRM & AzAPI providers. Preexisting Features Intelligent Code Completion: Benefit from context-aware suggestions, like property names or resource types. Code Samples: Quickly insert code samples for your resources: Paste as AzAPI: Copy your existing resource JSON or ARM Templates into VSCode with the Microsoft Terraform extension, and it will automatically convert your code into AzAPI. The below example takes a resource JSON from the Azure Portal and pastes it into VSCode as AzAPI: Migrate AzureRM to AzAPI: Move existing AzureRM code to the AzAPI provider whenever you wish to. Read more in the Guide to migrate AzureRM resources to AzAPI Feedback We value your feedback! You can share your experience with the Microsoft Terraform extension by running the command Microsoft Terraform: Show Survey from the Command Palette. Your input helps us improve the extension and better serve your needs. Conclusion Whether you are managing traditional Azure resources, modern Microsoft Graph environments, or a combination of both, the new MSGraph provider and Microsoft Terraform VS Code extension are designed to help you deliver robust, reliable infrastructure—faster and with greater confidence. Stay tuned for further updates, workshops, and community events as we continue to evolve these offerings. Your feedback and participation are invaluable as we build the next generation of infrastructure automation together.
Resilience Testing with Azure Chaos Studio: Compute Failures
Introduction Chaos Studio is an Azure service that helps you measure, understand, and build application and service resilience to real-world incidents, such as an unexpected infrastructure disruption or an application failure causing 100% CPU usage on a VM. In this new series of blog posts, we’ll share best practices on performing resilience tests for common failure scenarios, provide step-by-step tutorials, and discuss how to leverage test results to improve the resilience of your cloud applications. Today, we’ll focus on using Chaos Studio to simulate a compute failure. Resilience Testing Best Practices We recommend using a hypothesis-driven approach for resilience testing to ensure actionable results: Define a hypothesis: outline a specific failure scenario and predict how your infrastructure will perform if it occurs. Design a fault injection experiment that reflects the failure scenario you wish to test and set up proper telemetry to monitor performance over the course of the experiment. Run your experiment and analyze results to determine if your hypothesis was validated or invalidated. Make necessary improvements to your configurations based on your findings. As your cloud infrastructure changes and evolves, new dependency and configuration issues may arise – repeat this process over time to ensure continued reliability. Simulate a Compute Failure Scenario Today, we’ll be performing an Availability Zone shutdown on a Virtual Machine Scale Set configured with instances across multiple Availability Zones. Remember to define a hypothesis before conducting your resilience test, for example: “If one Availability Zone is shut down, the Virtual Machine Scale Set’s autoscale configuration will detect the drop in instance count and automatically provision additional instances in the remaining zones, maintaining overall capacity and performance.” Next, we’ll create and run a fault injection experiment to test our scenario using Chaos Studio. Prerequisites A valid Azure subscription. If you don’t have one, you can create a free account. A Virtual Machine Scale Set configured with instances across multiple availability zones. Ensure that it is located in a region supported by Azure Chaos Studio (Resource Targeting). If you don’t have one, you can follow the instructions to create one. If this is your first time using Chaos Studio, follow the instructions below to register the resource provider for your subscription Open the Azure portal. Search for and select Subscriptions. Select the subscription you’d like to use. Select Settings > Resource providers from the left-side menu. Search for and select Microsoft.Chaos. Select Register. Create an Experiment and Set Up Monitoring To create an Availability Zone shutdown experiment on your Virtual Machine Scale set, do the following: Open the Azure portal. Search for and select Chaos Studio. Select Targets from the left-side menu. Select the Virtual Machine Scale Set you’d like to test and select Enable targets > Enable service-direct targets (All resources) > Review + Enable > Enable. Navigate back to Chaos Studio and select Experiments from the left-side menu. Select Create > New experiment. On the Basics tab, select a subscription and resource group for your experiment. Give your experiment a name and select the region you’d like to store it in. On the Permissions tab, select whether you’d like to use a System or User-assigned managed identity to manage your experiment permissions. If you’re unsure of which to choose, select the system-assigned identity option. Check the Enable custom role creation and assignment checkbox – this will allow Chaos Studio to automatically assign the necessary permissions to your managed identity based on your experiment configuration. On the Experiment designer tab, select Add action > Add fault. Choose the VMSS Shutdown (version 2.0) fault from the dropdown. Select Next: Target resources and select your Virtual Machine Scale Set. Select Next: Scope, choose the zone you’d like to shut down, and select Add. Select the Review + create button, review the experiment configuration, and select Create. The metrics you should monitor for your experiment run depend on the hypothesis you came up with for your scenario. Since our sample hypothesis predicted that our Virtual Machine Scale Set would provision additional instances in the event of a disruption based on its autoscale setting, we’ll show you how to track the availability of your Virtual Machine Scale Set’s virtual machine instances: Search for your Virtual Machine Scale Set by name using the Azure portal search bar and select it to go to its overview page. Select Monitoring > Metrics from the left-side menu. Configure a metric with the following values: Scope: your Virtual Machine Scale Set Metric Namespace: Virtual Machine Host Metric: VM Availability Metric (Preview) Aggregation: Avg Select Add metric. You may select Save to dashboard and choose the Pin to dashboard, Pin to Grafana, or Send to workbook options to save your metric where you’d like. The VM Availability Metric will now display an average of the availability of your virtual machine instances within your Virtual Machine Scale Set over the course of your experiment run. Run the Experiment and Analyze Results To run your experiment, do the following: Within the Azure portal, navigate back to Chaos Studio and select Experiments from the left-side menu. Select your experiment and select Start experiment(s) > Yes from the bar at the top of the page. Select your experiment’s name to navigate to its overview page. Select the Details button under History to monitor its progress while running. While your experiment is running, navigate to your Virtual Machine Scale Set > Monitoring > Metrics, or the location where you saved your VM Availability Metric, and view the impact of the Availability Zone shutdown on your Virtual Machine Scale Set’s average instance availability: Recommendations to Improve Resiliency Did your Virtual Machine Scale Set perform as you expected it to during the Availability Zone shutdown? If not, here are some steps you can take to improve your resiliency for future tests and protect against real-world incidents: Configure or review the autoscale settings on your Virtual Machine Scale Set to ensure rapid provisioning of additional instances in unaffected zones during a failure. Maintain a balanced instance count across Availability Zones to minimize the impact of losing an entire zone. Set up load balancing or adjust configurations to seamlessly redistribute traffic when a zone becomes unavailable. After making improvements to your Virtual Machine Scale Set configuration, be sure to test and iterate on them by continuing to perform resilience testing regularly. Conclusion In this blog post, we have shown you how to use Chaos Studio to test your Virtual Machine Scale Sets against Availability Zone shutdowns. With the best practices laid out in this guide, you can conduct resilience tests on services across your cloud infrastructure using faults in Chaos Studio’s fault library. Be sure to look out for more blog posts covering other scenarios in the “Resilience Testing with Azure Chaos Studio” series soon. Feel free to add a comment below on which scenarios you’d like to see next. Happy resilience testing! Additional resources Chaos Studio Overview: http://aka.ms/AzureChaosStudio Documentation: Azure Chaos Studio documentation - tutorials, API reference MS Build Session Recording: https://www.youtube.com/watch?v=lk1yxLMj-7A Advancing Microsoft Azure resilience with Chaos Studio | Microsoft Azure Blog Regional availability of Azure Chaos Studio | Microsoft LearnIntroducing Azure Verified Modules!
Accelerate the delivery Infrastructure-as-Code solutions with Azure Verified Modules! AVM is a community-driven initiative that sets the standards for Infrastructure-as-Code modules within Microsoft and the engaged community. These atomic building blocks encapsulate groups of resources dedicated to one task and are used to deploy Azure resources and their extensions consistently. Stay tuned for more information on how AVM can help you reliably and consistently deliver at scale.
