# AWS FIS experiment template components
You use the following components to construct experiment templates:
**Actions**
The [AWS FIS actions](fis-actions-reference.md) that you want to run. Actions can be run in a set order that you specify, or they can be run simultaneously. For more information, see [Actions](action-sequence.md).
**Targets**
The AWS resources on which a specific action is carried out. For more information, see [Targets](targets.md).
**Stop conditions**
The CloudWatch alarms that define a threshold at which your application performance is not acceptable. If a stop condition is triggered while an experiment is running, AWS FIS stops the experiment. For more information, see [Stop conditions](stop-conditions.md).
**Experiment role**
An IAM role that grants AWS FIS the permissions required so that it can run experiments on your behalf. For more information, see [Experiment role](getting-started-iam-service-role.md).
**Experiment report configuration**
The configuration to enable experiment reports. For more information, see [Experiment report configurations for AWS FIS](experiment-report-configuration.md).
**Experiment options**
Options for the experiment template. For more information, see [Experiment options for AWS FIS](experiment-options.md).
Your account has quotas related to AWS FIS. For example, there is a quota on the number of actions per experiment template. For more information, see [Quotas and limitations](fis-quotas.md).
## Template syntax
The following is the syntax for an experiment template.
```
{
"description": "string",
"targets": {},
"actions": {},
"stopConditions": [],
"roleArn": "arn:aws:iam::123456789012:role/AllowFISActions",
"experimentReportConfiguration":{},
"experimentOptions":{},
"tags": {}
}
```
For examples, see [Example templates](experiment-template-example.md).
## Get started
To create an experiment template using the AWS Management Console, see [Create an experiment template](create-template.md).
To create an experiment template using the AWS CLI, see [Example AWS FIS experiment templates](experiment-template-example.md).
# Actions for AWS FIS
To create an experiment template, you must define one or more actions. For a list of predefined actions provided by AWS FIS, see [Actions reference](fis-actions-reference.md).
You can run an action only once during an experiment. To run the same AWS FIS action more than once in the same experiment, add it to the template multiple times using different names.
**Topics**
+ [
## Action syntax
](#action-syntax)
+ [
## Action identifiers
](#action-identifiers)
+ [
## Action parameters
](#action-parameters)
+ [
## Action targets
](#action-targets)
+ [
## Action duration
](#action-duration)
+ [
## Example actions
](#example-actions)
## Action syntax
The following is the syntax for an action.
```
{
"actions": {
"action_name": {
"actionId": "aws:service:action-type",
"description": "string",
"parameters": {
"name": "value"
},
"startAfter": ["action_name", ...],
"targets": {
"ResourceType": "target_name"
}
}
}
}
```
When you define an action, you provide the following:
***action\$1name***
A name for the action.
**actionId**
The [action identifier](#action-identifiers).
**description**
An optional description.
**parameters**
Any [action parameters](#action-parameters).
**startAfter**
Any actions that must complete before this action can start. Otherwise, the action runs at the start of the experiment.
**targets**
Any [action targets](#action-targets).
For examples, see [Example actions](#example-actions).
## Action identifiers
Each AWS FIS action has an identifier with the following format:
```
aws:service-name:action-type
```
For example, the following action stops the target Amazon EC2 instances:
```
aws:ec2:stop-instances
```
For a complete list of actions, see the [AWS FIS Actions reference](fis-actions-reference.md).
## Action parameters
Some AWS FIS actions have additional parameters that are specific to the action. These parameters are used to pass information to AWS FIS when the action is run.
AWS FIS supports custom fault types using the `aws:ssm:send-command` action, which uses the SSM Agent and an SSM command document to create the fault condition on the targeted instances. The `aws:ssm:send-command` action includes a `documentArn` parameter that takes the Amazon Resource Name (ARN) of an SSM document as a value. You specify values for parameters when you add the action to your experiment template.
For more information about specifying parameters for the `aws:ssm:send-command` action, see [Use the aws:ssm:send-command action](actions-ssm-agent.md#specifying-ssm-actions).
Where possible, you can input a rollback configuration (also referred to as a *post action*) within the action parameters. A post action returns the target to the state that it was in before the action was run. The post action runs after the time specified in the action duration. Not all actions can support post actions. For example, if the action terminates an Amazon EC2 instance, you cannot recover the instance after it has been terminated.
## Action targets
An action runs on the target resources that you specify. After you define a target, you can specify its name when you define an action.
```
"targets": {
"ResourceType": "resource_name"
}
```
AWS FIS actions support the following resource types for action targets:
+ **AutoScalingGroups** – Amazon EC2 Auto Scaling groups
+ **Buckets** – Amazon S3 buckets
+ **Cluster** – Amazon EKS clusters
+ **Clusters** – Amazon ECS, Aurora DSQL, or Amazon Aurora DB clusters
+ **DBInstances** – Amazon RDS DB instances
+ **Functions** – AWS Lambda functions
+ **Instances** – Amazon EC2 instances
+ **KinesisStreams** – Kinesis data streams
+ **ManagedResources** – Amazon EKS clusters, Amazon EC2 Application and Network Load Balancers, and Amazon EC2 Auto Scaling groups that are enabled for ARC zonal shift.
+ **MultiRegionClusters** – Amazon MemoryDB multi-Region clusters
+ **Nodegroups** – Amazon EKS node groups
+ **Pods** – Kubernetes pods on Amazon EKS
+ **ReplicationGroups** – ElastiCache Replication Groups
+ **Roles** – IAM roles
+ **SpotInstances** – Amazon EC2 Spot Instances
+ **Subnets** – VPC subnets
+ **Tables** – Amazon DynamoDB multi-Region strongly and eventually consistent global tables
+ **Tasks** – Amazon ECS tasks
+ **TransitGateways** – Transit gateways
+ **VirtualInterfaces** – Direct Connect Virtual Interfaces
+ **Volumes** – Amazon EBS volumes
+ **VPCEndpoints** – Amazon VPC endpoints
For examples, see [Example actions](#example-actions).
## Action duration
If an action includes a parameter that you can use to specify the duration of the action, by default, the action is considered complete only after the specified duration has elapsed. If you have set the `emptyTargetResolutionMode` experiment option to `skip`, then the action will complete immediately with status 'skipped' when no targets were resolved. For example, if you specify a duration of 5 minutes, AWS FIS considers the action complete after 5 minutes. It then starts the next action, until all actions are complete.
Duration can be either the length of time that an action condition is maintained or the length of time for which metrics are monitored. For example, latency is injected for the duration of time specified. For near instantaneous action types, such as terminating an instance, stop conditions are monitored for the duration of time specified.
If an action includes a post action within the action parameters, the post action runs after the action completes. The time it takes to complete the post action might cause a delay between the specified action duration and the beginning of the next action (or the end of the experiment, if all other actions are complete).
## Example actions
The following are example actions.
**Examples**
+ [Stop EC2 instances](#example-action-stop-instances)
+ [Interrupt Spot Instances](#example-action-send-spot-instance-interupptions)
+ [Disrupt network traffic](#example-action-disrupt-connectivity)
+ [Terminate EKS workers](#example-action-terminate-nodegroup-instances)
+ [Start ARC zonal autoshift](#example-start-arc-zonal-autoshift)
**Example: Stop EC2 instances**
The following action stops the EC2 instances identified using the target named *targetInstances*. After two minutes, it restarts the target instances.
```
"actions": {
"stopInstances": {
"actionId": "aws:ec2:stop-instances",
"parameters": {
"startInstancesAfterDuration": "PT2M"
},
"targets": {
"Instances": "targetInstances"
}
}
}
```
**Example: Interrupt Spot Instances**
The following action stops the Spot Instances identified using the target named *targetSpotInstances*. It waits two minutes before interrupting the Spot Instance.
```
"actions": {
"interruptSpotInstances": {
"actionId": "aws:ec2:send-spot-instance-interruptions",
"parameters": {
"durationBeforeInterruption": "PT2M"
},
"targets": {
"SpotInstances": "targetSpotInstances"
}
}
}
```
**Example: Disrupt network traffic**
The following action denies traffic between the target subnets and subnets in other Availability Zones.
```
"actions": {
"disruptAZConnectivity": {
"actionId": "aws:network:disrupt-connectivity",
"parameters": {
"scope": "availability-zone",
"duration": "PT5M"
},
"targets": {
"Subnets": "targetSubnets"
}
}
}
```
**Example: Terminate EKS workers**
The following action terminates 50% of the EC2 instances in the EKS cluster identified using the target named *targetNodeGroups*.
```
"actions": {
"terminateWorkers": {
"actionId": "aws:eks:terminate-nodegroup-instances",
"parameters": {
"instanceTerminationPercentage": "50"
},
"targets": {
"Nodegroups": "targetNodeGroups"
}
}
}
```
**Example: Start ARC zonal autoshift**
The following action starts an ARC Zonal autoshift that shifts managed resources away from *az-in-parameters* for *duration-in-parameteres*. The resource type `ManagedResources` is used as a key for the target name in AWS FIS experiment template.
```
{
"description": "aaa",
"targets": {
"ManagedResources-Target-1": {
"resourceType": "aws:arc:zonal-shift-managed-resource",
"resourceArns": [
"arn:aws:elasticloadbalancing:us-east-1:0124567890:loadbalancer/app/application/11223312312516",
],
"selectionMode": "ALL"
}
},
"actions": {
"arc": {
"actionId": "aws:arc:start-zonal-autoshift",
"parameters": {
"availabilityZoneIdentifier": "us-east-1a",
"duration": "PT1M"
},
"targets": {
"ManagedResources": "ManagedResources-Target-1"
}
}
},
"stopConditions": [
{
"source": "none"
}
],
"roleArn": "arn:aws:iam::718579638765:role/fis",
"tags": {},
"experimentOptions": {
"accountTargeting": "single-account",
"emptyTargetResolutionMode": "fail"
}
}
```
# Targets for AWS FIS
A target is one or more AWS resources on which an action is performed by AWS Fault Injection Service (AWS FIS) during an experiment. Targets can be in the same AWS account as the experiment, or in a different account using a multi-account experiment. To learn more about targeting resources in a different account, see [Working with multi-account experiments for AWS FIS](multi-account.md).
You define targets when you [create an experiment template](create-template.md). You can use the same target for multiple actions in your experiment template.
AWS FIS identifies all targets at the start of the experiment, before starting any of the actions in the actions set. AWS FIS uses the target resources that it selects for the entire experiment. If no targets are found, the experiment fails.
**Contents**
+ [
## Target syntax
](#target-syntax)
+ [
## Resource types
](#resource-types)
+ [
## Identify target resources
](#target-identification)
+ [
### Resource filters
](#target-filters)
+ [
### Resource parameters
](#target-parameters)
+ [
## Selection mode
](#target-selection-mode)
+ [
## Example targets
](#target-examples)
+ [
## Example filters
](#filter-examples)
## Target syntax
The following is the syntax for a target.
```
{
"targets": {
"target_name": {
"resourceType": "resource-type",
"resourceArns": [
"resource-arn"
],
"resourceTags": {
"tag-key": "tag-value"
},
"parameters": {
"parameter-name": "parameter-value"
},
"filters": [
{
"path": "path-string",
"values": ["value-string"]
}
],
"selectionMode": "value"
}
}
}
```
When you define a target, you provide the following:
**target\$1name**
A name for the target.
**resourceType**
The [resource type](#resource-types).
**resourceArns**
The Amazon Resource Names (ARN) of specific resources.
**resourceTags**
The tags applied to specific resources.
**parameters**
The [parameters](#target-parameters) that identify targets using specific attributes.
**filters**
The [resource filters](#target-filters) scopes the identified target resources using specific attributes.
**selectionMode**
The [selection mode](#target-selection-mode) for the identified resources.
For examples, see [Example targets](#target-examples).
## Resource types
Each AWS FIS action is performed on a specific AWS resource type. When you define a target, you must specify exactly one resource type. When you specify a target for an action, the target must be the resource type supported by the action.
The following resource types are supported by AWS FIS:
+ **aws:arc:zonal-shift-managed-resource** – An AWS resource that is registered with ARC zonal shift
+ **aws:directconnect:virtual-interface** – A Direct Connect Virtual Interface
+ **aws:dsql:cluster** – An Amazon Aurora DSQL cluster
+ **aws:dynamodb:global-table** – An Amazon DynamoDB multi-Region global table
+ **aws:ec2:autoscaling-group** – An Amazon EC2 Auto Scaling group
+ **aws:ec2:ebs-volume** – An Amazon EBS volume
+ **aws:ec2:instance** – An Amazon EC2 instance
+ **aws:ec2:spot-instance** – An Amazon EC2 Spot Instance
+ **aws:ec2:subnet** – An Amazon VPC subnet
+ **aws:ec2:transit-gateway** – A transit gateway
+ **aws:ec2:vpc-endpoint** – An Amazon VPC Endpoint
+ **aws:ecs:cluster** – An Amazon ECS cluster
+ **aws:ecs:task** – An Amazon ECS task
+ **aws:eks:cluster** – An Amazon EKS cluster
+ **aws:eks:nodegroup** – An Amazon EKS node group
+ **aws:eks:pod** – A Kubernetes pod
+ **aws:elasticache:replicationgroup** – An ElastiCache Replication Group
+ **aws:iam:role** – An IAM role
+ **aws:kinesis:stream** – An Amazon Kinesis data stream
+ **aws:lambda:function ** – An AWS Lambda function
+ **aws:memorydb:multi-region-cluster ** – An Amazon MemoryDB multi-Region cluster
+ **aws:rds:cluster** – An Amazon Aurora DB cluster
+ **aws:rds:db** – An Amazon RDS DB instance
+ **aws:s3:bucket** – An Amazon S3 bucket
## Identify target resources
When you define a target in the AWS FIS console, you can choose specific AWS resources (of a specific resource type) to target. Or, you can let AWS FIS identify a group of resources based on the criteria that you provide.
To identify your target resources, you can specify the following:
+ **Resource IDs** – The resource IDs of specific AWS resources. All resource IDs must represent the same type of resource.
+ **Resource tags** – The tags applied to specific AWS resources.
+ **Resource filters** – The path and values that represent resources with specific attributes. For more information, see [Resource filters](#target-filters).
+ **Resource parameters** – The parameters that represent resources that meet specific criteria. For more information, see [Resource parameters](#target-parameters).
**Considerations**
+ You can't specify both a resource ID and a resource tag for the same target.
+ You can't specify both a resource ID and a resource filter for the same target.
+ If you specify a resource tag with an empty tag value, it is not equivalent to a wildcard. It matches resources that have a tag with the specified tag key and an empty tag value.
+ If you specify more than one tag, all specified tags have to be present on the target resource for it to be selected (`AND`).
### Resource filters
Resource filters are queries that identify target resources according to specific attributes. AWS FIS applies the query to the output of an API action that contains the canonical description of the AWS resource, according to the resource type that you specify. Resources that have attributes that match the query are included in the target definition.
Each filter is expressed as an attribute path and possible values. A path is a sequence of elements, separated by periods, that describe the path to reach an attribute in the output of the **Describe** action for a resource. Each period stands for the expansion of an element. Each element must be expressed in Pascal case, even if the output of the **Describe** action for a resource is in camel case. For example, you should use `AvailabilityZone`, not `availablityZone` as an attribute element.
```
"filters": [
{
"path": "Component.Component.Component",
"values": [
"string"
]
}
],
```
The following logic applies to all resource filters:
+ If multiple filters are provided, including filters with the same path, all filters have to be matched for a resource to be selected – `AND`
+ If multiple values are provided for a single filter, any one value needs to be matched for a resource to be selected – `OR`
+ If multiple values are found at the path location of the describe API call, any one value needs to be matched for a resource to be selected – `OR`
+ To match on tag key/value pairs you should select target resources by tags instead (see above).
The following table includes the API actions and AWS CLI commands that you can use to get the canonical descriptions for each resource type. AWS FIS runs these actions on your behalf to apply the filters that you specify. The corresponding documentation describes the resources that are included in the results by default. For example, the documentation for **DescribeInstances** states that recently terminated instances might appear in the results.
| Resource type | API action | AWS CLI command |
| --- | --- | --- |
| aws:arc:zonal-shift-managed-resource | ListManagedResources | list-managed-resources |
| aws:directconnect:virtual-interface | [DescribeVirtualInterfaces](https://docs.aws.amazon.com/directconnect/latest/APIReference/API_DescribeVirtualInterfaces.html) | [describe-virtual-interfaces](https://docs.aws.amazon.com/cli/latest/reference/directconnect/describe-virtual-interfaces.html) |
| aws:ec2:autoscaling-group | [DescribeAutoScalingGroups](https://docs.aws.amazon.com/autoscaling/ec2/APIReference/API_DescribeAutoScalingGroups.html) | [describe-auto-scaling-groups](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/describe-auto-scaling-groups.html) |
| aws:ec2:ebs-volume | [DescribeVolumes](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVolumes.html) | [describe-volumes](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-volumes.html) |
| aws:ec2:instance | [DescribeInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html) | [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html) |
| aws:ec2:subnet | [DescribeSubnets](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html) | [describe-subnets](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-subnets.html) |
| aws:ec2:transit-gateway | [DescribeTransitGateways](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeTransitGateways.html) | [describe-transit-gateways](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-transit-gateways.html) |
| aws:ec2:vpc-endpoint | [DescribeVpcEndpoints](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeVpcEndpoints.html) | [describe-vpc-endpoints](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-vpc-endpoints.html) |
| aws:ecs:cluster | [DescribeClusters](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeClusters.html) | [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-clusters.html) |
| aws:ecs:task | [DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html) | [describe-tasks](https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-tasks.html) |
| aws:eks:cluster | [DescribeClusters](https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeClusters.html) | [describe-clusters](https://docs.aws.amazon.com/cli/latest/reference/eks/describe-clusters.html) |
| aws:eks:nodegroup | [DescribeNodegroup](https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeNodegroup.html) | [describe-nodegroup](https://docs.aws.amazon.com/cli/latest/reference/eks/describe-nodegroup.html) |
| aws:elasticache:replicationgroup | [DescribeReplicationGroups](https://docs.aws.amazon.com/AmazonElastiCache/latest/APIReference/API_DescribeReplicationGroups.html) | [describe-replication-groups](https://docs.aws.amazon.com/cli/latest/reference/elasticache/describe-replication-groups.html) |
| aws:iam:role | [ListRoles](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListRoles.html) | [list-roles](https://docs.aws.amazon.com/cli/latest/reference/iam/list-roles.html) |
| aws:kinesis:stream | [DescribeStreamSummary](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DescribeStreamSummary.html) | [describe-stream-summary](https://docs.aws.amazon.com/cli/latest/reference/kinesis/describe-stream-summary.html) |
| aws:lambda:function | [ListFunctions](https://docs.aws.amazon.com/lambda/latest/api/API_ListFunctions.html) | [list-functions](https://docs.aws.amazon.com/cli/latest/reference/lambda/list-functions.html) |
| aws:memorydb:multi-region-clustern | [DescribeMultiRegionClusters](https://docs.aws.amazon.com/memorydb/latest/APIReference/API_DescribeMultiRegionClusters.html) | [describe-multi-region-clusters](https://docs.aws.amazon.com/cli/latest/reference/memorydb/describe-multi-region-clusters.html) |
| aws:rds:cluster | [DescribeDBClusters](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBClusters.html) | [describe-db-clusters](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-clusters.html) |
| aws:rds:db | [DescribeDBInstances](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBInstances.html) | [describe-db-instances](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-instances.html) |
| aws:s3:bucket | [ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) | [list-buckets](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-buckets.html) |
| aws:dynamodb:global-table | [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) | [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) |
| aws:dsql:cluster | [GetCluster](https://docs.aws.amazon.com/aurora-dsql/latest/APIReference/API_GetCluster.html) | [get-cluster](https://docs.aws.amazon.com/cli/latest/reference/dsql/get-cluster.html) |
For examples, see [Example filters](#filter-examples).
### Resource parameters
Resource parameters identify target resources according to specific criteria.
The following resource type supports parameters.
**aws:ec2:ebs-volume**
+ `availabilityZoneIdentifier` – The code (for example, us-east-1a) of the Availability Zone that contains the target volumes.
**aws:ec2:subnet**
+ `availabilityZoneIdentifier` – The code (for example, us-east-1a) or AZ ID (for example, use1-az1) of the Availability Zone that contains the target subnets.
+ `vpc` – The VPC that contains the target subnets. Does not support more than one VPC per account.
**aws:ecs:task**
+ `cluster` – The cluster that contains the target tasks.
+ `service` – The service that contains the target tasks.
**aws:eks:pod**
+ `availabilityZoneIdentifier` – Optional. The Availability Zone that contains the target pods. For example, `us-east-1d`. We determine the Availability Zone of a pod by comparing its hostIP and the CIDR of the cluster subnet.
+ `clusterIdentifier` – Required. The name or ARN of the target EKS cluster.
+ `namespace` – Required. The Kubernetes namespace of the target pods.
+ `selectorType` – Required. The selector type. The possible values are `labelSelector`, `deploymentName`, and `podName`.
+ `selectorValue` – Required. The selector value. This value depends on the value of `selectorType`.
+ `targetContainerName` – Optional. The name of the target container as defined in the pod spec. The default is the first container defined in each target pod spec.
** aws:lambda:function **
+ `functionQualifier` – Optional. The version or alias of the function to target. If no qualifier is specified all invocations will be considered for targeting. If an alias with multiple versions is specified, all versions included in the alias will be considered for targeting as long as they are invoked using an ARN containing the alias. If the special alias `$LATEST` is used, invocations to the base function ARN and invocations including `$LATEST` in the ARN will be considered for fault injection. For more information on Lambda versions, see [Manage Lambda function versions](https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html) in the *AWS Lambda user guide*.
** aws:rds:cluster **
+ `writerAvailabilityZoneIdentifiers` – Optional. The Availability Zones of the writer of the DB cluster. Possible values are: a comma separated list of Availability Zone identifiers, `all`.
** aws:rds:db **
+ `availabilityZoneIdentifiers` – Optional. The Availability Zones of the DB instance to be affected. Possible values are: a comma separated list of Availability Zone identifiers, `all`.
**aws:elasticache:replicationgroup**
+ `availabilityZoneIdentifier` – Required. The code (for example, us-east-1a) or AZ ID (for example, use1-az1) of the Availability Zone that contains the target nodes.
## Selection mode
You scope the identified resources by specifying a selection mode. AWS FIS supports the following selection modes:
+ `ALL` – Run the action on all targets.
+ `COUNT(n)` – Run the action on the specified number of targets, chosen from the identified targets at random. For example, COUNT(1) selects one of the identified targets.
+ `PERCENT(n)` – Run the action on the specified percentage of targets, chosen from the identified targets at random. For example, PERCENT(25) selects 25% of the identified targets.
If you have an odd number of resources and specify 50%, AWS FIS rounds down. For example, if you add five Amazon EC2 instances as targets and scope to 50%, AWS FIS rounds down to two instances. You can't specify a percentage that is less than one resource. For example, if you add four Amazon EC2 instances and scope to 5%, AWS FIS can't select an instance.
If you define multiple targets using the same target resource type, AWS FIS can select the same resource multiple times.
Regardless of which selection mode you use, if the scope that you specify identifies no resources, the experiment fails.
## Example targets
The following are example targets.
**Examples**
+ [Instances in the specified VPC with the specified tags](#target-instances)
+ [Tasks with the specified parameters](#target-tasks)
**Example: Instances in the specified VPC with the specified tags**
The possible targets for this example are Amazon EC2 instances in the specified VPC with the tag env=prod. The selection mode specifies that AWS FIS chooses one of these targets at random.
```
{
"targets": {
"randomInstance": {
"resourceType": "aws:ec2:instance",
"resourceTags": {
"env": "prod"
},
"filters": [
{
"path": "VpcId",
"values": [
"vpc-aabbcc11223344556"
]
}
],
"selectionMode": "COUNT(1)"
}
}
}
```
**Example: Tasks with the specified parameters**
The possible targets for this example are Amazon ECS tasks with the specified cluster and service. The selection mode specifies that AWS FIS choose one of these targets at random.
```
{
"targets": {
"randomTask": {
"resourceType": "aws:ecs:task",
"parameters": {
"cluster": "myCluster",
"service": "myService"
},
"selectionMode": "COUNT(1)"
}
}
}
```
## Example filters
The following are example filters.
**Examples**
+ [EC2 instances](#filter-instances)
+ [DB clusters](#filter-db-clusters)
**Example: EC2 instances**
When you specify a filter for an action that supports the **aws:ec2:instance** resource type, AWS FIS uses the Amazon EC2 **describe-instances** command and applies the filter to identify the targets.
The **describe-instances** command returns JSON output where each instance is a structure under `Instances`. The following is partial output that includes fields marked with *italics*. We'll provide examples that use these fields to specify an attribute path from the structure of the JSON output.
```
{
"Reservations": [
{
"Groups": [],
"Instances": [
{
"ImageId": "ami-00111111111111111",
"InstanceId": "i-00aaaaaaaaaaaaaaa",
"InstanceType": "t2.micro",
"KeyName": "virginia-kp",
"LaunchTime": "2020-09-30T11:38:17.000Z",
"Monitoring": {
"State": "disabled"
},
"Placement": {
"AvailabilityZone": "us-east-1a",
"GroupName": "",
"Tenancy": "default"
},
"PrivateDnsName": "ip-10-0-1-240.ec2.internal",
"PrivateIpAddress": "10.0.1.240",
"ProductCodes": [],
"PublicDnsName": "ec2-203-0-113-17.compute-1.amazonaws.com",
"PublicIpAddress": "203.0.113.17",
"State": {
"Code": 16,
"Name": "running"
},
"StateTransitionReason": "",
"SubnetId": "subnet-aabbcc11223344556",
"VpcId": "vpc-00bbbbbbbbbbbbbbbbb",
...
"NetworkInterfaces": [
{
...
"Groups": [
{
"GroupName": "sec-group-1",
"GroupId": "sg-a0011223344556677"
},
{
"GroupName": "sec-group-1",
"GroupId": "sg-b9988776655443322"
}
],
...
},
...
},
...
{
...
}
],
"OwnerId": "123456789012",
"ReservationId": "r-aaaaaabbbbb111111"
},
...
]
}
```
To select instances in a specific Availability Zone using a resource filter, specify the attribute path for `AvailabilityZone` and the code for the Availability Zone as the value. For example:
```
"filters": [
{
"path": "Placement.AvailabilityZone",
"values": [ "us-east-1a" ]
}
],
```
To select instances in a specific subnet using a resource filter, specify the attribute path for `SubnetId` and the ID of the subnet as the value. For example:
```
"filters": [
{
"path": "SubnetId",
"values": [ "subnet-aabbcc11223344556" ]
}
],
```
To select instances that are in a specific instance state, specify the attribute path for `Name` and one of the following state names as the value: `pending` \$1 `running` \$1 `shutting-down` \$1 `terminated` \$1 `stopping` \$1 `stopped`. For example:
```
"filters": [
{
"path": "State.Name",
"values": [ "running" ]
}
],
```
To select instances that have *any* of a number of security groups attached, specify a single filter with the attribute path for `GroupId` and multiple security group IDs. For example:
```
"filters": [
{
"path": "NetworkInterfaces.Groups.GroupId",
"values": [
"sg-a0011223344556677",
"sg-f1100110011001100"
]
}
],
```
To select instances that have *all* of a number of security groups attached, specify multiple filters with the attribute path for `GroupId` and a single security group ID for each filter. For example:
```
"filters": [
{
"path": "NetworkInterfaces.Groups.GroupId",
"values": [
"sg-a0011223344556677"
]
},
{
"path": "NetworkInterfaces.Groups.GroupId",
"values": [
"sg-b9988776655443322"
]
}
],
```
**Example: Amazon RDS cluster (DB cluster)**
When you specify a filter for an action that supports the **aws:rds:cluster** resource type, AWS FIS runs the Amazon RDS **describe-db-clusters** command and applies the filter to identify the targets.
The **describe-db-clusters** command returns JSON output similar to the following for each DB cluster. The following is partial output that includes fields marked with *italics*. We'll provide examples that use these fields to specify an attribute path from the structure of the JSON output.
```
[
{
"AllocatedStorage": 1,
"AvailabilityZones": [
"us-east-2a",
"us-east-2b",
"us-east-2c"
],
"BackupRetentionPeriod": 7,
"DatabaseName": "",
"DBClusterIdentifier": "database-1",
"DBClusterParameterGroup": "default.aurora-postgresql11",
"DBSubnetGroup": "default-vpc-01234567abc123456",
"Status": "available",
"EarliestRestorableTime": "2020-11-13T15:08:32.211Z",
"Endpoint": "database-1.cluster-example.us-east-2.rds.amazonaws.com",
"ReaderEndpoint": "database-1.cluster-ro-example.us-east-2.rds.amazonaws.com",
"MultiAZ": false,
"Engine": "aurora-postgresql",
"EngineVersion": "11.7",
...
}
]
```
To apply a resource filter that returns only the DB clusters that use a specific DB engine, specify the attribute path as `Engine` and the value as `aurora-postgresql` as shown in the following example.
```
"filters": [
{
"path": "Engine",
"values": [ "aurora-postgresql" ]
}
],
```
To apply a resource filter that returns only the DB clusters in a specific Availability Zone, specify the attribute path and value as shown in the following example.
```
"filters": [
{
"path": "AvailabilityZones",
"values": [ "us-east-2a" ]
}
],
```
# Stop conditions for AWS FIS
AWS Fault Injection Service (AWS FIS) provides controls and guardrails for you to run experiments safely on AWS workloads. A *stop condition* is a mechanism to stop an experiment if it reaches a threshold that you define as an Amazon CloudWatch alarm. If a stop condition is triggered during an experiment, AWS FIS stops the experiment. You cannot resume a stopped experiment.
To create a stop condition, first define the steady state for your application or service. The steady state is when your application is performing optimally, defined in terms of business or technical metrics. For example, latency, CPU load, or number of retries. You can use the steady state to create a CloudWatch alarm that you can use to stop an experiment if your application or service reaches a state where its performance is not acceptable. For more information, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*.
Your account has a quota on the number of stop conditions that you can specify in an experiment template. For more information, see [Quotas and limitations for AWS Fault Injection Service](fis-quotas.md).
## Stop condition syntax
When you create an experiment template, you specify one or more stop conditions by specifying the CloudWatch alarms that you created.
```
{
"stopConditions": [
{
"source": "aws:cloudwatch:alarm",
"value": "arn:aws:cloudwatch:region:123456789012:alarm:alarm-name"
}
]
}
```
The following example indicates that the experiment template does not specify a stop condition.
```
{
"stopConditions": [
{
"source": "none"
}
]
}
```
## Learn more
For a tutorial that demonstrates how to create a CloudWatch alarm and add a stop condition to an experiment template, see [Run CPU stress on an instance](fis-tutorial-run-cpu-stress.md).
For more information about the CloudWatch metrics that are available for the resource types supported by AWS FIS, see the following:
+ [Monitor your instances using CloudWatch](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-cloudwatch.html)
+ [Amazon ECS CloudWatch metrics](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-metrics.html)
+ [Monitoring Amazon RDS metrics using CloudWatch](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/monitoring-cloudwatch.html)
+ [Monitoring Run Command metrics using CloudWatch](https://docs.aws.amazon.com/systems-manager/latest/userguide/monitoring-cloudwatch-metrics.html)
# IAM roles for AWS FIS experiments
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. To use AWS FIS, you must create an IAM role that grants AWS FIS the permissions required so that AWS FIS can run experiments on your behalf. You specify this experiment role when you create an experiment template. For a single-account experiment, the IAM policy for the experiment role must grant permission to modify the resources that you specify as targets in your experiment template. For a multi-account experiment, the experiment role must grant the orchestrator role permission to assume the IAM role for each target account. For more information, see [Permissions for multi-account experiments](multi-account-prerequisites.md#permissions).
We recommend that you follow the standard security practice of granting least privilege. You can do so by specifying specific resource ARNs or tags in your policies.
To help you get started with AWS FIS quickly, we provide AWS managed policies that you can specify when you create an experiment role. Alternatively, you can also use these policies as a model as you create your own inline policy documents.
**Topics**
+ [
## Prerequisites
](#create-fis-role-prereqs)
+ [
## Option 1: Create an experiment role and attach an AWS managed policy
](#fis-role-managed-policy)
+ [
## Option 2: Create an experiment role and add an inline policy document
](#fis-role-inline-policy-document)
## Prerequisites
Before you begin, install the AWS CLI and create the required trust policy.
**Install the AWS CLI**
Before you begin, install and configure the AWS CLI. When you configure the AWS CLI, you are prompted for AWS credentials. The examples in this procedure assume that you also configured a default Region. Otherwise, add the `--region` option to each command. For more information, see [Installing or updating the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).
**Create a trust relationship policy**
An experiment role must have a trust relationship that allows the AWS FIS service to assume the role. Create a text file named `fis-role-trust-policy.json` and add the following trust relationship policy.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"fis.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
We recommend that you use the `aws:SourceAccount` and `aws:SourceArn` condition keys to protect yourself against [the confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). The source account is the owner of the experiment and the source ARN is the ARN of the experiment. For example, you should add the following condition block to your trust policy.
```
"Condition": {
"StringEquals": {
"aws:SourceAccount": "account_id"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:fis:region:account_id:experiment/*"
}
}
```
**Add permissions to assume target account roles (multi-account experiments only)**
For multi-account experiments, you need permissions that allows orchestrator account to assume target account roles. You can modify the following example and add as an inline policy document to assume target account roles:
```
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource":[
"arn:aws:iam::target_account_id:role/role_name"
]
}
```
## Option 1: Create an experiment role and attach an AWS managed policy
Use one of the AWS managed policies from AWS FIS to get started quickly.
**To create an experiment role and attach an AWS managed policy**
1. Verify that there is a managed policy for the AWS FIS actions in your experiment. Otherwise, you'll need to create your own inline policy document instead. For more information, see [AWS managed policies for AWS Fault Injection Service](security-iam-awsmanpol.md).
1. Use the following [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) command to create a role and add the trust policy that you created in the prerequisites.
```
aws iam create-role --role-name my-fis-role --assume-role-policy-document file://fis-role-trust-policy.json
```
1. Use the following [attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html) command to attach the AWS managed policy.
```
aws iam attach-role-policy --role-name my-fis-role --policy-arn fis-policy-arn
```
Where *fis-policy-arn* is one of the following:
+ arn:aws:iam::aws:policy/service-role/AWSFaultInjectionSimulatorEC2Access
+ arn:aws:iam::aws:policy/service-role/AWSFaultInjectionSimulatorECSAccess
+ arn:aws:iam::aws:policy/service-role/AWSFaultInjectionSimulatorEKSAccess
+ arn:aws:iam::aws:policy/service-role/AWSFaultInjectionSimulatorNetworkAccess
+ arn:aws:iam::aws:policy/service-role/AWSFaultInjectionSimulatorRDSAccess
+ arn:aws:iam::aws:policy/service-role/AWSFaultInjectionSimulatorSSMAccess
## Option 2: Create an experiment role and add an inline policy document
Use this option for actions that don't have a managed policy, or to include only the permissions that are required for your specific experiment.
**To create an experiment and add an inline policy document**
1. Use the following [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) command to create a role and add the trust policy that you created in the prerequisites.
```
aws iam create-role --role-name my-fis-role --assume-role-policy-document file://fis-role-trust-policy.json
```
1. Create a text file named `fis-role-permissions-policy.json` and add a permissions policy. For an example that you can use as a starting point, see the following.
+ **Fault injection actions** – Start from the following policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowFISExperimentRoleFaultInjectionActions",
"Effect": "Allow",
"Action": [
"fis:InjectApiInternalError",
"fis:InjectApiThrottleError",
"fis:InjectApiUnavailableError"
],
"Resource": "arn:*:fis:*:*:experiment/*"
}
]
}
```
------
+ **Amazon EBS actions** – Start from the following policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:DescribeVolumes"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:PauseVolumeIO"
],
"Resource": "arn:aws:ec2:*:*:volume/*"
}
]
}
```
------
+ **Amazon EC2 actions** – Start from the [AWSFaultInjectionSimulatorEC2Access](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSFaultInjectionSimulatorEC2Access.html) policy.
+ **Amazon ECS actions** – Start from the [AWSFaultInjectionSimulatorECSAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSFaultInjectionSimulatorECSAccess.html) policy.
+ **Amazon EKS actions** – Start from the [AWSFaultInjectionSimulatorEKSAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSFaultInjectionSimulatorEKSAccess.html) policy.
+ **Network actions** – Start from the [AWSFaultInjectionSimulatorNetworkAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSFaultInjectionSimulatorNetworkAccess.html) policy.
+ **Amazon RDS actions** – Start from the [AWSFaultInjectionSimulatorRDSAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSFaultInjectionSimulatorRDSAccess.html) policy.
+ **Systems Manager actions** – Start from the [AWSFaultInjectionSimulatorSSMAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSFaultInjectionSimulatorSSMAccess.html) policy.
1. Use the following [put-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html) command to add the permissions policy that you created in the previous step.
```
aws iam put-role-policy --role-name my-fis-role --policy-name my-fis-policy --policy-document file://fis-role-permissions-policy.json
```
# Experiment report configurations for AWS FIS
You can enable AWS Fault Injection Service (FIS) to generate reports for experiments, making it easier to produce evidence of resilience testing. The experiment report is a PDF document that summarizes experiment actions and optionally captures application response from a CloudWatch dashboard that you specify. To see an example experiment report, download the zip file [here](samples/FisExampleReport.pdf.zip).
To enable and configure the contents of the report generated for the experiment, you define the experiment report configuration for the experiment template. When you specify a CloudWatch dashboard, AWS FIS includes a snapshot graph of all the widgets in the given dashboard annotated with experiment start and end time over a duration that you specify, as shown in the example below.
This example demonstrates the impact of a packet loss experiment in an Availability Zone (AZ). When packet loss is introduced in AZ use1-az6, traffic shifts away from use1-az6 and towards use1-az4, so that the number of bytes processed by the load balancer in that AZ declines.
![\[Two graphs showing ProcessedBytes over time, with one increasing and one decreasing sharply.\]](http://docs.aws.amazon.com/fis/latest/userguide/images/packet-loss-az-example.png)
When the experiment ends, the report can be downloaded from the AWS FIS console and is also stored in an Amazon S3 bucket. If you include a CloudWatch dashboard in your report configuration, images of each widget are also delivered. Reports are not generated for experiments that are `cancelled` or run as part of target preview (with **actionsMode** set to `skip-all`). Once the experiment exceeds the experiment data retention limit, the report will only be available from the Amazon S3 bucket. AWS FIS charges apply for each delivered report, except for those that fail with internal errors. For more information, see [AWS Fault Injection Service pricing](https://aws.amazon.com/fis/pricing/) and [Quotas and limitations for AWS Fault Injection Service](fis-quotas.md). Ingest and storage charges for Amazon S3 and CloudWatch API charges for **GetMetricWidgetImage** and **GetDashboard** requests may apply. For more information, see [Amazon S3 pricing](https://aws.amazon.com/s3/pricing/) and [CloudWatch pricing](https://aws.amazon.com/cloudwatch/pricing/).
**Topics**
+ [
## Experiment report configuration syntax
](#experiment-report-syntax)
+ [
## Experiment report permissions
](#experiment-report-permissions)
+ [
## Experiment report best practices
](#experiment-report-best-practices)
## Experiment report configuration syntax
The following is the syntax for the experiment report configuration, an optional section of the experiment template.
```
{
"experimentReportConfiguration": {
"outputs": {
"s3Configuration": {
"bucketName": "my-bucket-name",
"prefix": "report-storage-prefix"
}
},
"dataSources": {
"cloudWatchDashboards": [
{
"dashboardIdentifier": "arn:aws:cloudwatch::123456789012:dashboard/MyDashboard"
}
]
},
"preExperimentDuration": "PT20M",
"postExperimentDuration": "PT20M"
}
}
```
Using the `experimentReportConfiguration`, you can customize the output destination, input data, and time windows for the data to include in the experiment report, which can help you better understand the impact and results of your AWS FIS experiments. When you define the experiment report configuration, you provide the following:
**outputs**
Section of the `experimentReportConfiguration` that specifies where the experiment report will be delivered. In `outputs`, you specify the `s3Configuration` by providing the following:
+ `bucketName` - The name of the Amazon S3 bucket where the report will be stored. The bucket must be in the same region as the experiment.
+ `prefix` (Optional) - A prefix within the Amazon S3 bucket where the report will be stored. This field is strongly recommended so that you can limit access to the prefix only.
**dataSources**
Optional section of the `experimentReportConfiguration` that specifies the additional data sources that will be included in the experiment report.
+ `cloudWatchDashboards` - An array of the CloudWatch dashboards that will be included in the report. Limited to one CloudWatch dashboard.
+ `dashboardIdentifier`- The ARN of the CloudWatch dashboard. Snapshot graphs of every widget with the type `metric` in this dashboard will be included in the report, with the exception of cross-region metrics.
**preExperimentDuration**
Optional section of the `experimentReportConfiguration` that defines the pre-experiment duration for the CloudWatch dashboard metrics to include in the report, up to 30 minutes. This should be a period that represents your application steady state. For example, a pre-experiment duration of 5 minutes means the snapshot graphs will include metrics 5 minutes before the experiment starts. The format for the duration is ISO 8601 and the default is 20 minutes.
**postExperimentDuration**
Optional section of the `experimentReportConfiguration` that defines the post-experiment duration for the CloudWatch dashboard metrics to include in the report, up to 2 hours. This should be a duration that represents your application steady state or recovery period. For example, if you specify a post-experiment duration of 5 minutes, the snapshot graphs will include metrics until 5 minutes after the experiment ends. The format for the duration is ISO 8601 and the default is 20 minutes.
## Experiment report permissions
To enable AWS FIS to generate and store the experiment report, you need to allow the following operations from your AWS FIS experiment IAM role:
+ `cloudwatch:GetDashboard`
+ `cloudwatch:GetMetricWidgetImage`
+ `s3:GetObject`
+ `s3:PutObject`
We recommend you follow AWS security best practices and restrict the experiment role to the bucket and prefix. The following is an example policy statement that restricts the experiment role access.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":
[
{
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": "arn:aws:s3:::my-experiment-report-bucket/my-prefix/*",
"Effect": "Allow"
},
{
"Action": [
"cloudwatch:GetDashboard"
],
"Resource": "arn:aws:cloudwatch::012345678912:dashboard/my-experiment-report-dashboard",
"Effect": "Allow"
},
{
"Action": [
"cloudwatch:GetMetricWidgetImage"
],
"Resource": "*",
"Effect": "Allow"
}
]
}
```
------
### Additional permissions for reports delivered to Amazon S3 buckets encrypted with customer managed keys (CMK)
If the Amazon S3 bucket you specify in the `S3Configuration` is encrypted with CMK, you need to grant the following additional permissions to the FIS experiment role on your KMS key policy:
+ `kms:GenerateDataKey`
+ `kms:Decrypt`
The following is an example KMS key policy statement that allows the FIS experiment role to write reports to encrypted buckets:
```
{
"Sid": "Allow FIS experiment report",
"Effect": "Allow",
"Principal":
{
"AWS": [
"arn:aws:iam::012345678912:role/FISExperimentRole",
]
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "*"
}
```
## Experiment report best practices
The following are best practices for using the AWS FIS experiment report configuration:
+ Before you start an experiment, generate a target preview to verify that your experiment template is configured as you expect. The target preview will give you information about the expected targets of your experiment. To learn more, see [Generate a target preview from an experiment template](generate-target-preview.md).
+ The report should not be used for troubleshooting failed experiments. Instead, use experiment logs to troubleshoot experiment errors. We recommend that you rely on the report only for experiments that you have previously run and successfully completed.
+ Restrict the experiment IAM role put and get object access to the S3 destination bucket and prefix. We recommend that you dedicate the bucket / prefix to AWS FIS experiment reports only, and do not grant other AWS services access to this bucket and prefix.
+ Use Amazon S3 Object Lock to prevent the report from getting being deleted or overwritten for a fixed amount of time or indefinitely. To learn more, see [Locking objects with Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html).
+ If your CloudWatch dashboard is in a separate account within the same region, you can use CloudWatch cross-account observability to enable your AWS FIS orchestrator account as the monitoring account and the separate account as the source account from the CloudWatch console or Observability Access Manager commands in the AWS CLI and API. To learn more, see [CloudWatch cross-account observability](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html).
# Experiment options for AWS FIS
Experiment options are optional settings for an experiment. You can define certain experiment options on the experiment template. Additional experiment options are set when you begin the experiment.
The following is the syntax for experiment options that you define on the experiment template.
```
{
"experimentOptions": {
"accountTargeting": "single-account | multi-account",
"emptyTargetResolutionMode": "fail | skip"
}
}
```
If you do not specify any experiment options when you create the experiment template, the default for each option is used.
The following is the syntax for experiment options that you set when you begin the experiment.
```
{
"experimentOptions": {
"actionsMode": "run-all | skip-all"
}
}
```
If you do not specify any experiment options when you begin the experiment, the default `run-all` is used.
**Topics**
+ [
## Account targeting
](#account-targeting)
+ [
## Empty target resolution mode
](#empty-target-resolution-mode)
+ [
## Actions mode
](#actions-mode)
## Account targeting
If you have multiple AWS accounts with resources that you want to target in an experiment, you can define a multi-account experiment using the account targeting experiment option. You run multi-account experiments from an orchestrator account that impacts resources in multiple target accounts. The orchestrator account owns the AWS FIS experiment template and experiment. A target account is an individual AWS account with resources that can be affected by an AWS FIS experiment. For more information, see [Working with multi-account experiments for AWS FIS](multi-account.md).
You use account targeting to indicate the location of your target resources. You can provide two values for account targeting:
+ **single-account** – Default. The experiment will only target resources in the AWS account where AWS FIS experiment runs.
+ **multi-account** – The experiment can target resources in multiple AWS accounts.
### Target account configurations
To run a multi-account experiment, you must define one or more target account configurations. A target account configuration specifies the accountId, roleArn, and description for each account with resources targeted in the experiment. The account IDs of the target account configurations for an experiment template must be unique.
When you create a multi-account experiment template, the experiment template will return a read-only field, `targetAccountConfigurationsCount`, that is a count of all the target account configurations for the experiment template.
The following is the syntax for a target account configuration.
```
{
accountId: "123456789012",
roleArn: "arn:aws:iam::123456789012:role/AllowFISActions",
description: "fis-ec2-test"
}
```
When you create a target account configuration, you provide the following:
**accountId**
12-digit AWS account ID of the target account.
**roleArn**
An IAM Role granting AWS FIS permissions to take actions in target account.
**description**
An optional description.
To learn more about how to work with target account configurations, see [Working with multi-account experiments for AWS FIS](multi-account.md).
## Empty target resolution mode
This mode gives you the option to allow experiments to complete even when a target resource is not resolved.
+ **fail** – Default. If no resources are resolved for the target, the experiment is terminated immediately with a status of `failed`.
+ **skip** – If no resources are resolved for the target, the experiment will continue and any actions with no resolved targets are skipped. Actions with targets that are defined using unique identifiers, such as ARNs, cannot be skipped. If a target defined using a unique identifier is not found the experiment is terminated immediately with a status of `failed`
## Actions mode
Actions mode is an optional parameter that you can specify when you start an experiment. You can set actions mode to `skip-all` to generate a target preview before injecting faults into your target resources. The target preview allows you to verify the following:
+ That you have configured your experiment template to target the resources you expect. The actual resources that are targeted when you start this experiment may be different from the preview because resources may be removed, updated, or sampled randomly.
+ That your logging configurations are set up correctly.
+ That for multi-account experiments you have correctly set up an IAM role for each of your target account configurations.
**Note**
The `skip-all` mode does not allow you to verify that you have the necessary permissions to run the AWS FIS experiment and take actions on your resources.
The actions mode parameter accepts the following values:
+ `run-all` - (Default) The experiment will take actions on target resources.
+ `skip-all` - The experiment will skip all actions on target resources.
To learn more about how to set the actions mode parameter when you start an experiment, see [Generate a target preview from an experiment template](generate-target-preview.md).