Use REST APIs to interact with Chaos Studio

Article
10/14/2024

If you're integrating Azure Chaos Studio into your CI/CD pipelines, or you simply prefer to use direct API calls to interact with your Azure resources, you can use Chaos Studio's REST API. For the full API reference, visit the Azure Chaos Studio REST API reference. This page provides samples for using the REST API effectively, and is not intended as a comprehensive reference.

This article assumes you're using Azure CLI to execute these commands, but you can adapt them to other standard REST clients.

You can use the Chaos Studio REST APIs to:

Create, modify, and delete experiments
View, start, and stop experiment executions
View and manage targets
Register and unregister your subscription with the Chaos Studio resource provider
View available resource provider operations.

Use the az cli utility to perform these actions from the command line.

Tip

To get more verbose output with Azure CLI, append --verbose to the end of each command. This variable returns more metadata when commands execute, including x-ms-correlation-request-id, which aids in debugging.

These examples have been reviewed with the generally available Chaos Studio API version 2023-11-01.

Resource provider commands

This section lists the Chaos Studio provider commands, which help you understand the resource provider's status and available operations.

List details about the Microsoft.Chaos resource provider

This shows information such as available API versions for the Chaos resource provider and region availability. The most recent api-version required for this may differ from the api-version for Chaos resource provider operations.

az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos?api-version={apiVersion}"

List all the operations of the Microsoft.Chaos resource provider

az rest --method get --url "https://management.azure.com/providers/Microsoft.Chaos/operations?api-version={apiVersion}"

Targets and capabilities

These operations help you see what targets and capabilities are available, and add them to a target.

List all target types available in a region

az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos/locations/{locationName}/targetTypes?api-version={apiVersion}"

List all capabilities available for a target type

az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos/locations/{locationName}/targetTypes/{targetType}/capabilityTypes?api-version={apiVersion}"

Enable a resource as a target

To use a resource in an experiment, you need to enable it as a target.

az rest --method put --url "https://management.azure.com/{resourceId}/providers/Microsoft.Chaos/targets/{targetType}?api-version={apiVersion}" --body "{'properties':{}}"

Enable capabilities for a target

Once a resource has been enabled as a target, you need to specify what capabilities (corresponding to faults) are allowed.

az rest --method put --url "https://management.azure.com/{resourceId}/providers/Microsoft.Chaos/targets/{targetType}/capabilities/{capabilityName}?api-version={apiVersion}" --body "{'properties':{}}"

See what capabilities are enabled for a target

Once a target and capabilities have been enabled, you can view the enabled capabilities. This is useful for constructing your chaos experiment, since it includes the parameter schema for each fault.

az rest --method get --url "https://management.azure.com/{resourceId}/providers/Microsoft.Chaos/targets/{targetType}/capabilities?api-version={apiVersion}"

Experiments

These operations help you view, run, and manage experiments.

List all the experiments in a resource group

az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Chaos/experiments?api-version={apiVersion}"

Get an experiment's configuration details by name

az rest --method get --url "https://management.azure.com/{experimentId}?api-version={apiVersion}"

Create or update an experiment

az rest --method put --url "https://management.azure.com/{experimentId}?api-version={apiVersion}" --body @{experimentName.json}

Note: if you receive an UnsupportedMediaType error, make sure your referenced JSON file is valid, and try other ways to reference the .json file. Different command-line interpreters may require different methods of file referencing. Another common syntax is --body "@experimentName.json".

Delete an experiment

az rest --method delete --url "https://management.azure.com/{experimentId}?api-version={apiVersion}"

Start an experiment

az rest --method post --url "https://management.azure.com/{experimentId}/start?api-version={apiVersion}"

Get all executions of an experiment

az rest --method get --url "https://management.azure.com/{experimentId}/executions?api-version={apiVersion}"

List the details of a specific experiment execution

If an experiment has failed, this can be used to find error messages and specific targets, branches, steps, or actions that failed.

az rest --method post --url "https://management.azure.com/{experimentId}/executions/{executionDetailsId}/getExecutionDetails?api-version={apiVersion}"

Cancel (stop) an experiment

az rest --method post --url "https://management.azure.com/{experimentId}/cancel?api-version={apiVersion}"

Other helpful commands and tips

While these commands don't use the Chaos Studio API specifically, they can be helpful for using Chaos Studio effectively.

View Chaos Studio resources with Azure Resource Graph

You can use the Azure Resource Graph REST API to query resources associated with Chaos Studio, like targets and capabilities.

 az rest --method post --url "https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01" --body "{'query':'chaosresources'}"

Alternatively, you can use Azure Resource Graph's az cli extension.

az graph query -q "chaosresources | summarize count() by type"

For example, if you want a summary of all the Chaos Studio targets active in your subscription by resource group, you can use:

az graph query -q "chaosresources | where type == 'microsoft.chaos/targets' | summarize count() by resourceGroup"

Filtering and querying

Like other Azure CLI commands, you can use the --query and --filter parameters with the Azure CLI rest commands. For example, to see a table of available capability types for a specific target type, use the following command:

az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos/locations/{locationName}/targetTypes/{targetType}/capabilityTypes?api-version=2023-11-01" --output table --query 'value[].{name:name, faultType:properties.runtimeProperties.kind, urn:properties.urn}'

Parameter definitions

This section describes the parameters used throughout this document and how you can fill them in.

Parameter name	Definition	Lookup	Example
{apiVersion}	Version of the API to use when you execute the command provided	Can be found in the API documentation	`2023-11-01`
{experimentId}	Azure Resource ID for the experiment	Can be found on the Chaos Studio Experiment page or with a GET call to the `/experiments` endpoint	`/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Chaos/experiments/my-chaos-experiment`
{experimentName.json}	JSON that contains the configuration of the chaos experiment	Generated by the user	`experiment.json` (See a CLI tutorial for a full example file)
{subscriptionId}	Subscription ID where the target resource is located	Find in the Azure portal Subscriptions page or by running `az account list --output table`	`aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e`
{resourceGroupName}	Name of the resource group where the target resource is located	Find in the Resource Groups page or by running `az group list --output table`	`my-resource-group`
{executionDetailsId}	Execution ID of an experiment execution	Find in the Chaos Studio Experiment page or with a GET call to the `/executions` endpoint	`C69E7FCD-1548-47E5-9DDA-92A5DD60E610`
{targetType}	Type of target for the corresponding resource	Find in the Fault providers list or a GET call to the `/locations/{locationName}/targetTypes` endpoint	`Microsoft-VirtualMachine`
{capabilityName}	Name of an individual capability resource, extending a target resource	Find in the fault reference documentation or with a GET call to the `capabilityTypes` endpoint	`Shutdown-1.0`
{locationName}	Azure region for a resource or regional endpoint	Find all possible regions for your account with `az account list-locations --output table`	`eastus`

Share via