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)

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.

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:ecs:task – An Amazon ECS task

  • aws:eks:cluster – An Amazon EKS 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. 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 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 cannot specify resource IDs and resource filters in 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, 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:ecs:task DescribeTasks describe-tasks
aws:eks: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" ] } ],

Resource parameters

Resource parameters identify target resources according to specific criteria.

The following resource type supports parameters.

aws:ecs:task
  • cluster – The cluster that contains the target tasks.

  • service – The service that contains the target tasks.

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.

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