Work with multi-account experiments

You can create and manage multi-account experiment templates using the AWS FIS console or the command line. You create a multi-account experiment by specifying the account targeting experiment option as "multi-account", and adding target account configurations. After you create a multi-account experiment template, you can use it to run an experiment.

Best practices for multi-account experiments

The following are best practices to using multi-account experiments:

• When you configure targets for multi-account experiments, we recommend targeting with consistent resource tags across all target accounts. An AWS FIS experiment will resolve resources with consistent tags in each target account. An action must resolve at least one target resource in any target account or will fail, except for experiments with emptyTargetResolutionMode set to skip. Action quotas apply per account. If you want to target resources by resource ARNs, the same single-account limit per action applies.

• When you target resources in one or more availability zones using parameters or filters, you should specify an AZ ID, not an AZ name. The AZ ID is a unique and consistent identifier for an Availability Zone across accounts. To learn how to find the AZ ID for the availability zones in your account, see Availability Zone IDs for your AWS resources.

Create a multi-account experiment template

To learn how to create an experiment template via the AWS Management Console

See Create an experiment template.

To create an experiment template using the CLI

1. Open the AWS Command Line Interface

2. To create an experiment from a saved JSON file with the account targeting experiment option set to "multi-account" (for example, my-template.json), replace the placeholder values in italics with your own values, and then run the following create-experiment-template command.

   aws fis create-experiment-template --cli-input-json file://my-template.json

   This will return the experiment template in the response. Copy the id from the response, which is the ID of the experiment template.

3. Run the create-target-account-configuration command to add a target account configuration to the experiment template. Replace the placeholder values in italics with your own values, using the id from step 2 as the value for the --experiment-template-id parameter, and then run the following. The --description parameter is optional. Repeat this step for each target account.

   aws fis create-target-account-configuration --experiment-template-id EXTxxxxxxxxx --account-id 111122223333 --role-arn arn:aws:iam::111122223333:role/role-name --description "my description"

4. Run the get-target-account-configuration command to retrieve the details for a specific target account configuration.

   aws fis get-target-account-configuration --experiment-template-id EXTxxxxxxxxx --account-id 111122223333

5. Once you have added all your target account configurations, you can run the list-target-account-configurations command command to see that your target account configurations have been created.

   aws fis list-target-account-configurations --experiment-template-id EXTxxxxxxxxx

   You can also verify that you have added target account configurations by running the get-experiment-template command. The template will return a read-only field targetAccountConfigurationsCount that is a count of all the target account configurations on the experiment template.

6. When you are ready, you can run the experiment template using the start-experiment command.

   aws fis start-experiment --experiment-template-id EXTxxxxxxxxx

Update a target account configuration

You can update an existing target account configuration if you want to change the role ARN or description for the the account. When you update a target account configuration, the changes do not affect any running experiments that use the template.

To update a target account configuration using the AWS Management Console

1. Open the AWS FIS console at https://console.aws.amazon.com/fis/.

2. In the navigation pane, choose Experiment templates

3. Select the experiment template, and choose Actions, Update experiment template.

4. Modify the target account configurations, and choose Update experiment template.

To update a target account configuration using the CLI

Run the update-target-account-configuration command to command, replacing the placeholder values in italics with your own values. The --role-arn and --description parameters are optional, and will not be updated if not included.

aws fis update-target-account-configuration --experiment-template-id EXTxxxxxxxxx --account-id 111122223333 --role-arn arn:aws:iam::111122223333:role/role-name --description "my description"

Delete a target account configuration

If you no longer need a target account configuration, you can delete it. When you delete a target account configuration, any running experiments that use the template are not affected. The experiment continues to run until completed or stopped.

To delete a target account configuration using the AWS Management Console

1. Open the AWS FIS console at https://console.aws.amazon.com/fis/.

2. In the navigation pane, choose Experiment templates.

3. Select the experiment template, and choose Actions, Update.

4. Under Target account configurations, select Remove for the target account Role ARN you want to delete.

To delete a target account configuration using the CLI

Run the delete-target-account-configuration command, replacing the placeholder values in italics with your own values.

aws fis update-target-account-configuration --experiment-template-id EXTxxxxxxxxx --account-id 111122223333