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.

You define targets when you create an experiment template. 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.

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"
        }
    }
}

For examples, see Example targets.

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.

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 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 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.

For examples, see Example filters.

Resource parameters

Resource parameters identify target resources according to specific criteria.

The following resource type supports parameters.

Selection mode

You scope the identified resources by specifying a selection mode. AWS FIS supports the following selection modes:

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.

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.

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 | running | shutting-down | terminated | stopping | 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" ] 
    }
],