Target syntax Resource types Identify target resources Selection mode Example targets Example filters

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

When you define a target, you provide the following:

target_name: A name for the target.
resourceType: The resource type.
resourceArns: The Amazon Resource Names (ARN) of specific resources.
resourceTags: The tags applied to specific resources.
parameters: The parameters that identify targets using specific attributes.
filters: The resource filters scopes the identified target resources using specific attributes.
selectionMode: The selection mode for the identified resources.

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.

The following resource types are supported by AWS FIS:

aws:dynamodb:global-table – An Amazon DynamoDB 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: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:redis-replicationgroup – An ElastiCache Redis Replication Group
aws:iam:role – An IAM role
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.
Resource parameters – The parameters that represent resources that meet specific criteria. For more information, see Resource 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.

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

Resource type	API action	AWS CLI command
aws:ec2:autoscaling-group	DescribeAutoScalingGroups	describe-auto-scaling-groups
aws:ec2:ebs-volume	DescribeVolumes	describe-volumes
aws:ec2:instance	DescribeInstances	describe-instances
aws:ec2:subnet	DescribeSubnets	describe-subnets
aws:ec2:transit-gateway	DescribeTransitGateways	describe-transit-gateways
aws:ecs:cluster	DescribeClusters	describe-clusters
aws:ecs:task	DescribeTasks	describe-tasks
aws:eks:cluster	DescribeClusters	describe-clusters
aws:eks:nodegroup	DescribeNodegroup	describe-nodegroup
aws:elasticache:redis-replicationgroup	DescribeReplicationGroups	describe-replication-groups
aws:iam:role	ListRoles	list-roles
aws:rds:cluster	DescribeDBClusters	describe-db-clusters
aws:rds:db	DescribeDBInstances	describe-db-instances
aws:s3:bucket	ListBuckets	list-buckets

The following logic applies to all resource filters:

Values inside a filter – OR
Values across filters – AND

For examples, see Example filters.

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: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:redis-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
Tasks with the specified parameters

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",
                    ...
                },
                ...
                {
                    ...
                }
            ],
            "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" ]
    }
],


"filters": [
    {
        "path": "State.Name",
        "values": [ "running" ]
    }
],

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

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Action set

Stop conditions

Targets for AWS FIS

Contents

Target syntax

Resource types

Identify target resources

Considerations

Resource filters

Resource parameters

Selection mode

Example targets

Examples

Example: Instances in the specified VPC with the specified tags

Example: Tasks with the specified parameters

Example filters

Examples

Example: EC2 instances

Example: Amazon RDS cluster (DB cluster)