Edit

Manage Workspaces and Scenarios with the Azure CLI

Use the Azure Chaos Studio CLI extension (az chaos) to manage Chaos Studio Workspaces and Scenarios from the command line. This guide covers resource discovery, permission configuration, validation, Scenario runs, and cleanup in a preproduction environment.

Important

Chaos Studio Workspaces and Scenarios are in public preview. Microsoft provides this preview "as is" and "as available," and it isn't covered by service-level agreements or limited warranty. Microsoft provides customer support for the preview on a best-effort basis. This preview isn't meant for production use. For more information, see the following articles:

The az chaos extension targets Chaos Studio Workspaces. To script Experiments (classic) instead, see Create a chaos experiment that uses an agent-based fault with the Azure CLI.

Prerequisites

  • An Azure subscription. If you don't have an Azure account, create a free account before you begin.
  • The Azure CLI. To install or upgrade it, see How to install the Azure CLI. You can also run these commands in Azure Cloud Shell.
  • At least one deployed Azure resource supported by a Scenario in Chaos Studio Workspaces.
  • The Microsoft.Chaos resource provider registered in your subscription. To register it, run az provider register --namespace Microsoft.Chaos.
  • Permission to create resources and role assignments in the target scope. The bootstrap step grants the Workspace identity the Reader role on the scope, and permission fixing assigns the roles each scenario needs. You need the Owner or User Access Administrator role, or an equivalent custom role, to assign roles. If you want to manage role assignments yourself, use the --skip-permissions option.

Install the extension

Install the extension from the public Azure CLI extension index:

az extension add --name chaos

If you already have the extension, update it to the latest version:

az extension update --name chaos

Sign in and select the subscription you want to work in:

az login
az account set --subscription "<subscription-name-or-id>"

Bootstrap a workspace with one command

The az chaos setup command creates a ready-to-use environment in a single step. It:

  1. Creates the resource group if it doesn't already exist.
  2. Creates a workspace with a managed identity.
  3. Grants that identity the Reader role on each scope you specify.
  4. Discovers the supported resources in scope and evaluates which scenarios apply.
  5. Prints the recommended scenarios and the commands to run next.

Run setup, replacing the placeholders with your values:

az chaos setup \
  --name <workspace-name> \
  --resource-group <resource-group> \
  --location <region> \
  --scopes "/subscriptions/<subscription-id>/resourceGroups/<target-resource-group>"

Keep the following points in mind:

  • Use --scopes to declare which resources Chaos Studio can target. Pass one or more resource IDs, separated by spaces. A scope can be a subscription (/subscriptions/<subscription-id>), a resource group, or a service group. To copy a resource group's ID, run az group show --name <resource-group> --query id --output tsv.
  • You only need to provide --location when the resource group doesn't already exist. When the group exists, setup reuses its location.
  • Use --user-assigned <identity-resource-id> to assign your own managed identity instead of a system-assigned one.
  • Use --skip-permissions to skip the Reader grant when you manage role assignments yourself.

When setup finishes, it lists the scenarios recommended for the resources it found, ranked by how well they apply.

The workspace discovered the following resources in scope:

az chaos discovered-resource list \
  --workspace-name <workspace-name> \
  --resource-group <resource-group> \
  --output table

The workspace recommends the following scenarios for those resources:

az chaos scenario list \
  --workspace-name <workspace-name> \
  --resource-group <resource-group> \
  --output table

If a list looks stale, trigger a new discovery and evaluation:

az chaos workspace refresh-recommendation \
  --name <workspace-name> \
  --resource-group <resource-group>

Configure a scenario

A scenario configuration defines the parameters and resource filters for a run. Create one from a recommended scenario:

az chaos scenario config create \
  --workspace-name <workspace-name> \
  --resource-group <resource-group> \
  --scenario-name <scenario-name> \
  --name <config-name> \
  --parameters "[{key:duration,value:PT10M}]" \
  --filters "{locations:[<region>],zones:[1]}"

Keep the following points in mind:

  • --scenario-name is the name of a scenario from az chaos scenario list, such as ComputeZoneDown-1.1.
  • --parameters takes a list of key/value objects. Use it to set values a scenario supports, such as the run duration in ISO 8601 format, where PT10M is 10 minutes. You can also pass a file with --parameters @parameters.json.
  • --filters narrows the targeted resources by locations, zones, or physical-zones. The zones and physical-zones keys are mutually exclusive. This option sets the earlier filters model.

In the 2026-08-01-preview REST API, resourceTargeting replaces the earlier filters and exclusions properties. You can't combine the two models. To migrate a configuration or create an include and exclude policy that targets resources by Azure tag, resource type, or resource ID, see Filter resources for Chaos Studio Workspace Scenarios.

Validate and fix permissions

Validate the configuration before you run it. Validation checks that the Workspace identity has the roles needed to run the Scenario against the targeted resources:

az chaos scenario config validate \
  --workspace-name <workspace-name> \
  --resource-group <resource-group> \
  --scenario-name <scenario-name> \
  --name <config-name>

If validation reports missing permissions, assign the required roles automatically:

az chaos scenario config fix-permissions \
  --workspace-name <workspace-name> \
  --resource-group <resource-group> \
  --scenario-name <scenario-name> \
  --name <config-name>

To preview the role assignments without making them, add --what-if.

Re-run validate until it passes. Azure role assignments can take a few minutes to propagate, so validation might still report that permissions require attention for a short time after you fix them.

Run the scenario

Start a run from the configuration. By default, run start performs a pre-flight validation and then executes:

az chaos scenario run start \
  --workspace-name <workspace-name> \
  --resource-group <resource-group> \
  --scenario-name <scenario-name> \
  --config-name <config-name>

The command returns a run ID. Check the run's status:

az chaos scenario run show \
  --workspace-name <workspace-name> \
  --resource-group <resource-group> \
  --scenario-name <scenario-name> \
  --run-id <run-id> \
  --output table

To stop a run before it finishes:

az chaos scenario run cancel \
  --workspace-name <workspace-name> \
  --resource-group <resource-group> \
  --scenario-name <scenario-name> \
  --run-id <run-id>

After a run completes, review its Scenario report to see which Actions ran and how your resources responded. See Scenario reports in Azure Chaos Studio.

Run the steps individually (optional)

The az chaos setup command wraps the granular commands behind one workflow verb. To control each step yourself, run them directly:

az chaos workspace create \
  --name <workspace-name> \
  --resource-group <resource-group> \
  --location <region> \
  --scopes "/subscriptions/<subscription-id>/resourceGroups/<target-resource-group>" \
  --system-assigned ""

az chaos workspace refresh-recommendation \
  --name <workspace-name> \
  --resource-group <resource-group>

Grant the Workspace identity the roles it needs by using az role assignment create, or let az chaos scenario config fix-permissions handle it per configuration.

Clean up resources

When you're done, delete the resources you created to avoid ongoing charges:

az group delete --name <resource-group> --yes --no-wait

If you scoped the Workspace to resources outside the deleted resource group, remove any role assignments granted to the Workspace identity.

Report issues and request features

Azure Chaos Studio is developed in the open. To report a bug, request a feature, or ask a question about Workspaces, Scenarios, or the Azure CLI extension, open an issue in the Chaos Studio repository on GitHub. By filing an issue, you can track its progress and see requests from other customers.

Related content

  • Last updated on