Targets for AWS FIS - AWS Fault Injection Simulator

Targets for AWS FIS

A target is one or more AWS resources on which an action is performed by AWS Fault Injection Simulator (AWS FIS) during an experiment. You define targets when you create an experiment template. You can use the same target for multiple actions in your experiment template.

When you define a target, you specify the following:

  • The resource type

  • How to identify the resources (through resource IDs, filters, or tags)

  • Which of the identified resources to run the action on (the selection mode)

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:ec2:instance – An Amazon EC2 instance

  • aws:ec2:spot-instance – An Amazon EC2 Spot Instance

  • aws:ecs:cluster – An Amazon ECS cluster

  • aws:eks:nodegroup – An Amazon EKS node group

  • aws:iam:role – An IAM role

  • aws:rds:cluster – An Amazon Aurora DB cluster

  • aws:rds:db – An Amazon RDS DB instance

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 in your account. 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. For example, the resource ID of an Amazon EC2 instance, such as i-1122334455aabbccd. All resource IDs must be the same resource type.

  • Resource filters – The path and values that represent resources with specific attributes. For more information, see Resource filters.

  • Resource tags – The tags applied to target resources. For example, you can specify that the target EC2 instances must include the tag env=test.

You must specify at least one resource ID or at least one resource tag for the target. You cannot specify both a resource ID and a resource tag for the same target. You also cannot specify resource IDs and resource filters in the same target.

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, the describe the path to reach an attribute in the output of the Describe action for a resource.

"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:instance DescribeInstances describe-instances
aws:ecs:cluster DescribeClusters describe-clusters
aws:eks:nodegroup DescribeNodegroup describe-nodegroup
aws:iam:role ListRoles list-roles
aws:rds:cluster DescribeDBClusters describe-db-clusters
aws:rds:db DescribeDBInstances describe-db-instances

The following logic applies to all resource filters:

  • Values inside a filter – OR

  • Values across filters – AND

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

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

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

Selection mode

By default, AWS FIS runs an action on all of the targets that are identified by the resource IDs, filters, or tags that you provide. Alternatively, you can scope the identified resources as follows:

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

Regardless of which selection mode you use, if the scope that you specify identifies no resources, the experiment fails.

Example target

The following is an example of a target:

  • Name: RandomTestInstance

  • Resource type: aws:ec2:instance

  • Filter: Attribute path: VpcId, Value: vpc-aabbcc11223344556

  • Resource tag: env = prod

  • Selection mode: COUNT (1)

The resources for this target are Amazon EC2 instances in the specified VPC with the tag env=prod. The selection mode specifies that one instance that meets this criteria is chosen at random.

{ "RandomTestInstance": { "resourceType": "aws:ec2:instance", "resourceTags": { "env": "prod" }, "filters": [ { "path": "VpcId", "values": [ "vpc-aabbcc11223344556" ] } ], "selectionMode": "COUNT(1)" } }