Skip to content

Commit 22a63db

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #262739 from rsgel/rigel-chaos-restfixes
fixes to Chaos REST API sample
2 parents 3c9f868 + e3c2ab9 commit 22a63db

File tree

1 file changed

+104
-60
lines changed

1 file changed

+104
-60
lines changed

‎articles/chaos-studio/chaos-studio-samples-rest-api.md

Lines changed: 104 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Use the REST APIs to manage Azure Chaos Studio experiments
3-
description: Run and manage a chaos experiment with Azure Chaos Studio by using REST APIs.
2+
title: Use REST APIs to interact with Chaos Studio
3+
description: Create, view, and manage Azure Chaos Studio experiments, targets, and capabilities with REST APIs.
44
services: chaos-studio
55
author: prasha-microsoft
66
ms.topic: article
@@ -10,139 +10,183 @@ ms.service: chaos-studio
1010
ms.custom: ignite-fall-2021, devx-track-azurecli
1111
---
1212

13-
# Use the Chaos Studio REST APIs to run and manage chaos experiments
13+
# Use REST APIs to interact with Chaos Studio
1414

15-
> [!WARNING]
16-
> Injecting faults can affect your application or service. Be careful not to disrupt customers.
15+
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](/rest/api/chaosstudio/). This page provides samples for using the REST API effectively, and is not intended as a comprehensive reference.
1716

18-
The Azure Chaos Studio REST API provides support for starting experiments programmatically. You can also use the Azure Resource Manager client and the Azure CLI to execute these commands from the console. The examples in this article are for the Azure CLI.
17+
This article assumes you're using [Azure CLI](/cli/azure/install-azure-cli) to execute these commands, but you can adapt them to other standard REST clients.
1918

20-
> [!Warning]
21-
> These APIs are still under development and subject to change.
22-
23-
## REST APIs
2419

2520
You can use the Chaos Studio REST APIs to:
26-
* Start, stop, and manage experiments.
27-
* View and manage targets.
28-
* Query experiment status.
29-
* Query and delete subscription configurations.
21+
* Create, modify, and delete experiments
22+
* View, start, and stop experiment executions
23+
* View and manage targets
24+
* Register and unregister your subscription with the Chaos Studio resource provider
25+
* View available resource provider operations.
3026

31-
Use the `AZ CLI` utility to perform these actions from the command line.
27+
Use the `az cli` utility to perform these actions from the command line.
3228

3329
> [!TIP]
34-
> To get more verbose output with the AZ 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.
30+
> 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.
31+
32+
These examples have been reviewed with the generally available Chaos Studio API version `2023-11-01`.
3533

36-
### Chaos Studio provider commands
34+
## Resource provider commands
3735

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

40-
#### List details about the Microsoft.Chaos resource provider
38+
### List details about the Microsoft.Chaos resource provider
39+
40+
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.
4141

4242
```azurecli
43-
az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos?api-version={apiVersion}" --resource "https://management.azure.com"
43+
az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos?api-version={apiVersion}"
4444
```
4545

46-
#### List all the operations of the Microsoft.Chaos resource provider
46+
### List all the operations of the Microsoft.Chaos resource provider
4747

4848
```azurecli
49-
az rest --method get --url "https://management.azure.com/providers/Microsoft.Chaos/operations?api-version={apiVersion}" --resource "https://management.azure.com"
49+
az rest --method get --url "https://management.azure.com/providers/Microsoft.Chaos/operations?api-version={apiVersion}"
5050
```
5151

52-
#### List Chaos provider configurations
52+
## Targets and capabilities
53+
54+
These operations help you see what [targets and capabilities](chaos-studio-targets-capabilities.md) are available, and add them to a target.
55+
56+
### List all target types available in a region
5357

5458
```azurecli
55-
az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/microsoft.chaos/chaosProviderConfigurations/?api-version={apiVersion}" --resource "https://management.azure.com" --verbose
59+
az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos/locations/{locationName}/targetTypes?api-version={apiVersion}"
5660
```
5761

58-
#### Create Chaos provider configuration
62+
### List all capabilities available for a target type
5963

6064
```azurecli
61-
az rest --method put --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/microsoft.chaos/chaosProviderConfigurations/{chaosProviderType}?api-version={apiVersion}" --body @{providerSettings.json} --resource "https://management.azure.com"
65+
az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos/locations/{locationName}/targetTypes/{targetType}/capabilityTypes?api-version={apiVersion}"
6266
```
6367

64-
### Chaos Studio target and agent commands
68+
### Enable a resource as a target
6569

66-
This section lists the Chaos Studio target and agent commands.
70+
To use a resource in an experiment, you need to enable it as a target.
6771

68-
#### List all the targets or agents under a subscription
72+
```azurecli
73+
az rest --method put --url "https://management.azure.com/{resourceId}/providers/Microsoft.Chaos/targets/{targetType}?api-version={apiVersion}" --body "{'properties':{}}"
74+
```
75+
76+
### Enable capabilities for a target
77+
78+
Once a resource has been enabled as a target, you need to specify what capabilities (corresponding to faults) are allowed.
6979

7080
```azurecli
71-
az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Chaos/chaosTargets/?api-version={apiVersion}" --url-parameter "chaosProviderType={chaosProviderType}" --resource "https://management.azure.com"
81+
az rest --method put --url "https://management.azure.com/{resourceId}/providers/Microsoft.Chaos/targets/{targetType}/capabilities/{capabilityName}?api-version={apiVersion}" --body "{'properties':{}}"
7282
```
7383

74-
### Chaos Studio experiment commands
84+
### See what capabilities are enabled for a target
85+
86+
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.
87+
88+
```azurecli
89+
az rest --method get --url "https://management.azure.com/{resourceId}/providers/Microsoft.Chaos/targets/{targetType}/capabilities?api-version={apiVersion}"
90+
```
7591

76-
This section lists the Chaos Studio experiment commands.
92+
## Experiments
7793

78-
#### List all the experiments in a resource group
94+
These operations help you view, run, and manage experiments.
95+
96+
### List all the experiments in a resource group
7997

8098
```azurecli
81-
az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Chaos/chaosExperiments?api-version={apiVersion}" --resource "https://management.azure.com"
99+
az rest --method get --url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Chaos/experiments?api-version={apiVersion}"
82100
```
83101

84-
#### Get an experiment's configuration details by name
102+
### Get an experiment's configuration details by name
85103

86104
```azurecli
87-
az rest --method get --url "https://management.azure.com/{experimentId}?api-version={apiVersion}" --resource "https://management.azure.com"
105+
az rest --method get --url "https://management.azure.com/{experimentId}?api-version={apiVersion}"
88106
```
89107

90-
#### Create or update an experiment
108+
### Create or update an experiment
91109

92110
```azurecli
93-
az rest --method put --url "https://management.azure.com/{experimentId}?api-version={apiVersion}" --body @{experimentName.json} --resource "https://management.azure.com"
111+
az rest --method put --url "https://management.azure.com/{experimentId}?api-version={apiVersion}" --body @{experimentName.json}
94112
```
95113

96-
#### Delete an experiment
114+
### Delete an experiment
97115

98116
```azurecli
99-
az rest --method delete --url "https://management.azure.com/{experimentId}?api-version={apiVersion}" --resource "https://management.azure.com" --verbose
117+
az rest --method delete --url "https://management.azure.com/{experimentId}?api-version={apiVersion}"
100118
```
101119

102-
#### Start an experiment
120+
### Start an experiment
103121

104122
```azurecli
105123
az rest --method post --url "https://management.azure.com/{experimentId}/start?api-version={apiVersion}"
106124
```
107125

108-
#### Get past statuses of an experiment
126+
### Get all executions of an experiment
109127

110128
```azurecli
111-
az rest --method get --url "https://management.azure.com/{experimentId}/statuses?api-version={apiVersion}" --resource "https://management.azure.com"
129+
az rest --method get --url "https://management.azure.com/{experimentId}/executions?api-version={apiVersion}"
112130
```
113131

114-
#### Get the status of an experiment
132+
### List the details of a specific experiment execution
133+
134+
If an experiment has failed, this can be used to find error messages and specific targets, branches, steps, or actions that failed.
115135

116136
```azurecli
117-
az rest --method get --url "https://management.azure.com/{experimentId}/status?api-version={apiVersion}" --resource "https://management.azure.com"
137+
az rest --method post --url "https://management.azure.com/{experimentId}/executions/{executionDetailsId}/getExecutionDetails?api-version={apiVersion}"
118138
```
119139

120-
#### Cancel (stop) an experiment
140+
### Cancel (stop) an experiment
121141

122142
```azurecli
123-
az rest --method get --url "https://management.azure.com/{experimentId}/cancel?api-version={apiVersion}" --resource "https://management.azure.com"
143+
az rest --method post --url "https://management.azure.com/{experimentId}/cancel?api-version={apiVersion}"
124144
```
125145

126-
#### List the details of the last two experiment executions
146+
## Other helpful commands and tips
147+
148+
While these commands don't use the Chaos Studio API specifically, they can be helpful for using Chaos Studio effectively.
149+
150+
### View Chaos Studio resources with Azure Resource Graph
151+
152+
You can use the Azure Resource Graph [REST API](../governance/resource-graph/first-query-rest-api.md) to query resources associated with Chaos Studio, like targets and capabilities.
127153

128154
```azurecli
129-
az rest --method get --url "https://management.azure.com/{experimentId}/executiondetails?api-version={apiVersion}" --resource "https://management.azure.com"
155+
az rest --method post --url "https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01" --body "{'query':'chaosresources'}"
156+
```
157+
158+
Alternatively, you can use Azure Resource Graph's `az cli` [extension](../governance/resource-graph/first-query-azurecli.md).
159+
160+
```azurecli-interactive
161+
az graph query -q "chaosresources | summarize count() by type"
162+
```
163+
164+
For example, if you want a summary of all the Chaos Studio targets active in your subscription by resource group, you can use:
165+
166+
```azurecli-interactive
167+
az graph query -q "chaosresources | where type == 'microsoft.chaos/targets' | summarize count() by resourceGroup"
130168
```
131169

132-
#### List the details of a specific experiment execution
170+
### Filtering and querying
171+
172+
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:
133173

134174
```azurecli
135-
az rest --method get --url "https://management.azure.com/{experimentId}/executiondetails/{executionDetailsId}?api-version={apiVersion}" --resource "https://management.azure.com"
175+
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}'
136176
```
137177

138178
## Parameter definitions
139179

140-
| Parameter name | Definition | Lookup |
141-
| --- | --- | --- |
142-
| {apiVersion} | Version of the API to use when you execute the command provided | Can be found in the [API documentation](/rest/api/chaosstudio/) |
143-
| {experimentId} | Azure Resource ID for the experiment | Can be found on the [Chaos Studio Experiment page](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.chaos%2Fchaosexperiments) |
144-
| {chaosProviderType} | Type or Name of Chaos Studio provider | Available providers can be found in the [List of current Provider Config Types](chaos-studio-fault-providers.md) |
145-
| {experimentName.json} | JSON that contains the configuration of the chaos experiment | Generated by the user |
146-
| {subscriptionId} | Subscription ID where the target resource is located | Can be found on the [Subscriptions page](https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade) |
147-
| {resourceGroupName} | Name of the resource group where the target resource is located | Can be found on the [Resource groups page](https://portal.azure.com/#blade/HubsExtension/BrowseResourceGroups) |
148-
| {executionDetailsId} | Execution ID of an experiment execution | Can be found on the [Chaos Studio Experiment page](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.chaos%2Fchaosexperiments) |
180+
This section describes the parameters used throughout this document and how you can fill them in.
181+
182+
| Parameter name | Definition | Lookup | Example |
183+
| --- | --- | --- | --- |
184+
| {apiVersion} | Version of the API to use when you execute the command provided | Can be found in the [API documentation](/rest/api/chaosstudio/) | `2023-11-01` |
185+
| {experimentId} | Azure Resource ID for the experiment | Can be found on the [Chaos Studio Experiment page](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.chaos%2Fchaosexperiments) or with a [GET call](#list-all-the-experiments-in-a-resource-group) to the `/experiments` endpoint | `/subscriptions/6b052e15-03d3-4f17-b2e1-be7f07588291/resourceGroups/my-resource-group/providers/Microsoft.Chaos/experiments/my-chaos-experiment` |
186+
| {experimentName.json} | JSON that contains the configuration of the chaos experiment | Generated by the user | `experiment.json` (See [a CLI tutorial](chaos-studio-tutorial-service-direct-cli.md) for a full example file) |
187+
| {subscriptionId} | Subscription ID where the target resource is located | Find in the [Azure portal Subscriptions page](https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade) or by running `az account list --output table` | `6b052e15-03d3-4f17-b2e1-be7f07588291` |
188+
| {resourceGroupName} | Name of the resource group where the target resource is located | Find in the [Resource Groups page](https://portal.azure.com/#blade/HubsExtension/BrowseResourceGroups) or by running `az group list --output table` | `my-resource-group` |
189+
| {executionDetailsId} | Execution ID of an experiment execution | Find in the [Chaos Studio Experiment page](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.chaos%2Fchaosexperiments) or with a [GET call](#get-all-executions-of-an-experiment) to the `/executions` endpoint | `C69E7FCD-1548-47E5-9DDA-92A5DD60E610` |
190+
| {targetType} | Type of target for the corresponding resource | Find in the [Fault providers list](chaos-studio-fault-providers.md) or a [GET call](#list-all-target-types-available-in-a-region) to the `/locations/{locationName}/targetTypes` endpoint | `Microsoft-VirtualMachine` |
191+
| {capabilityName} | Name of an individual capability resource, extending a target resource | Find in the [fault reference documentation](chaos-studio-fault-library.md) or with a [GET call](#list-all-capabilities-available-for-a-target-type) to the `capabilityTypes` endpoint | `Shutdown-1.0` |
192+
| {locationName} | Azure region for a resource or regional endpoint | Find all possible regions for your account with `az account list-locations --output table` | `eastus` |

0 commit comments

Comments
 (0)