Create an experiment role using the AWS CLI Required trust relationship policy Example inline policy documents

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. The IAM policy for the experiment role must grant permission to modify the resources that you specify as targets in your experiment template.

As a best practice, 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.

Contents

Create an experiment role using the AWS CLI
Required trust relationship policy
Example inline policy documents

Create an experiment role using the AWS CLI

Use one of the following options when you create the role:

Attach an AWS managed policy – With this option, you can get started quickly.
Add an inline policy document – With this option, you can remove permissions that are not required for your specific use case.

Option 1: Create an experiment role and attach an AWS managed policy

To create an experiment role and attach an AWS managed policy

Create a text file named fis-role-trust-policy.json and add the trust relationship policy described in Required trust relationship policy.
Use the following create-role command to create a role and add the trust policy that you created in the previous step.
```
aws iam create-role --role-name my-fis-role --assume-role-policy-document file://fis-role-trust-policy.json
```
Use the following attach-role-policy 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
For more information, see AWS managed policies for AWS Fault Injection Simulator.

Option 2: Create an experiment role and add an inline policy document

To create an experiment and add an inline policy document

Create a text file named fis-role-trust-policy.json and add the trust relationship policy described in Required trust relationship policy.
Use the following create-role command to create a role and add the trust policy that you created in the previous step.
```
aws iam create-role --role-name my-fis-role --assume-role-policy-document file://fis-role-trust-policy.json
```
Create a text file named fis-role-permissions-policy.json and add a permissions policy. For more information, see Example inline policy documents.

Use the following put-role-policy 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

Required trust relationship policy

An experiment role must have a trust relationship that allows the AWS FIS service to assume the role.


{
    "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. The source account is the owner of the experiment and the source ARN is the ARN of the experiment. For example, you could 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/*"
    }
}

Example inline policy documents

An experiment role must include a permissions policy that grants AWS FIS permission to run the experiment on your behalf. The specific policy statements that you must include depend on which AWS FIS actions you include in your experiment.

Example: Permissions for Amazon EBS actions

The following policy grants AWS FIS permission to use the AWS FIS actions for Amazon EBS. For more information about which AWS FIS actions require each permission, see AWS FIS actions for Amazon EBS.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeVolumes"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:PauseVolumeIO"
            ],
            "Resource": "arn:aws:ec2:*:*:volume/*"
        }
    ]
}

Example: Permissions for Amazon EC2 actions

The following policy grants AWS FIS permission to use the AWS FIS actions for Amazon EC2. For more information about which AWS FIS actions require each permission, see AWS FIS actions for Amazon EC2.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowFISExperimentRoleEC2Actions",
            "Effect": "Allow",
            "Action": [
                "ec2:RebootInstances",
                "ec2:StopInstances",
                "ec2:StartInstances",
                "ec2:TerminateInstances"
            ],
            "Resource": "arn:aws:ec2:*:*:instance/*"
        },
        {
            "Sid": "AllowFISExperimentRoleSpotInstanceActions",
            "Effect": "Allow",
            "Action": [
                "ec2:SendSpotInstanceInterruptions"
            ],
            "Resource": "arn:aws:ec2:*:*:instance/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:SendCommand"
            ],
            "Resource": [
                "arn:aws:ec2:*:*:instance/*",
                "arn:aws:ssm:*:*:document/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:CancelCommand",
                "ssm:ListCommands"
            ],
            "Resource": "*"
        }
    ]
}

If your experiment uses the aws:ec2:stop-instances action to stop and then start an instance with an encrypted EBS volume, you must also grant AWS FIS permission to the KMS key used to encrypt the volume, or add the experiment role to the KMS key policy. The following example allows the AWS FIS to create grants on the specified KMS key.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "kms:CreateGrant",
            "Resource": [
                "arn:aws:kms:*:*:key/*"
            ],
            "Condition": {
                "StringLike": {
                    "kms:ViaService": "ec2.*.amazonaws.com"
                },
                "Bool": {
                    "kms:GrantIsForAWSResource": true
                }
            }
        }
    ]
}

Example: Permissions for Amazon ECS actions

The following policy grants AWS FIS permission to use the AWS FIS actions for Amazon ECS. For more information about which AWS FIS actions require each permission, see AWS FIS actions for Amazon ECS.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowFISExperimentRoleECSUpdateState",
            "Effect": "Allow",
            "Action": [
                "ecs:UpdateContainerInstancesState"
            ],
            "Resource": "arn:aws:ecs:*:*:container-instance/*"
        },
        {
            "Sid": "AllowFISExperimentRoleECSStopTask",
            "Effect": "Allow",
            "Action": [
                "ecs:StopTask"
            ],
            "Resource": "arn:aws:ecs:*:*:task/*"
        }
    ]
}

Example: Permissions for Amazon EKS actions

The following policy grants AWS FIS permission to use the AWS FIS actions for Amazon EKS. For more information about which AWS FIS actions require each permission, see AWS FIS actions for Amazon EKS.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:TerminateInstances"
            ],
            "Resource": "arn:aws:ec2:*:*:instance/*"
        }
    ]
}

Example: Permissions for network actions

The follow policy grants AWS FIS permission to use the AWS FIS network actions. For more information about which AWS FIS actions require each permission, see Network actions.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ec2:CreateTags",
            "Resource": "arn:aws:ec2:*:*:network-acl/*",
            "Condition": {
                "StringEquals": {
                    "ec2:CreateAction": "CreateNetworkAcl",
                    "aws:RequestTag/managedByFIS": "true"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": "ec2:CreateNetworkAcl",
            "Resource": "arn:aws:ec2:*:*:network-acl/*",
            "Condition": {
                "StringEquals": {
                    "aws:RequestTag/managedByFIS": "true"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:CreateNetworkAclEntry",
                "ec2:DeleteNetworkAcl"
            ],
            "Resource": [
                "arn:aws:ec2:*:*:network-acl/*",
                "arn:aws:ec2:*:*:vpc/*"
            ],
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/managedByFIS": "true"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": "ec2:CreateNetworkAcl",
            "Resource": "arn:aws:ec2:*:*:vpc/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeVpcs",
                "ec2:DescribeManagedPrefixLists",
                "ec2:DescribeSubnets",
                "ec2:DescribeNetworkAcls"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "ec2:ReplaceNetworkAclAssociation",
            "Resource": [
                "arn:aws:ec2:*:*:subnet/*",
                "arn:aws:ec2:*:*:network-acl/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": "ec2:GetManagedPrefixListEntries",
            "Resource": "arn:aws:ec2:*:*:prefix-list/*"
        }
    ]
}

Example: Permissions for Amazon RDS actions

The following policy grants AWS FIS permission to use the AWS FIS actions for Amazon RDS. For more information about which AWS FIS actions require each permission, see AWS FIS actions for Amazon RDS.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowFISExperimentRoleRDSReboot",
            "Effect": "Allow",
            "Action": [
                "rds:RebootDBInstance"
            ],
            "Resource": "arn:aws:rds:*:*:db:*"
        },
        {
            "Sid": "AllowFISExperimentRoleRDSFailOver",
            "Effect": "Allow",
            "Action": [
                "rds:FailoverDBCluster"
            ],
            "Resource": "arn:aws:rds:*:*:cluster:*"
        }
    ]
}

Example: Permissions for Systems Manager actions

The following policy grants AWS FIS permission to use the AWS FIS actions for Systems Manager. For more information about which AWS FIS actions require each permission, see AWS FIS actions for Systems Manager.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowFISExperimentRoleSSMReadOnly",
            "Effect": "Allow",
            "Action": [
                "ssm:GetAutomationExecution",
                "ssm:ListCommands"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowFISExperimentRoleSSMSendCommand",
            "Effect": "Allow",
            "Action": [
                "ssm:SendCommand"
            ],
            "Resource": [
                "arn:aws:ec2:*:*:instance/*",
                "arn:aws:ssm:*:*:document/*"
            ]
        },
        {
            "Sid": "AllowFISExperimentRoleSSMCancelCommand",
            "Effect": "Allow",
            "Action": [
                "ssm:CancelCommand"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowFISExperimentRoleSSMAutomation",
            "Effect": "Allow",
            "Action": [
                "ssm:StartAutomationExecution",
                "ssm:StopAutomationExecution"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowFISExperimentRoleSSMAutomationPassRole",
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": "arn:aws:iam::account_id:role/role_name"
        }
    ]
}

Example: Permissions for fault injection actions

The following policy grants AWS FIS permission to use the AWS FIS actions for fault injection.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowFISExperimentRoleFaultInjectionActions",
            "Effect": "Allow",
            "Action": [
                "fis:InjectApiInternalError",
                "fis:InjectApiThrottleError",
                "fis:InjectApiUnavailableError"
            ],
            "Resource": "arn:*:fis:*:*:experiment/*"
        }
    ]
}

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

Stop conditions

Work with experiment templates