IAM Roles

Your AWS agent requires two IAM roles. A task role and a task execution role.

If you're using the "Advanced CloudFormation" template to install the agent, these IAM Roles are created for you and require no alteration. However, you do need to know the ARN of your platform key and database passwords and secrets during installation.

This topic describes the process and policies to create these roles, and the resources they should have access to.

Note

You need to add a policy to the S3 bucket used for staging. This is discussed in our topic S3 buckets and can be done independently of this topic.

---

Creating IAM roles

You should complete this process twice. Once for the task role and once for the task execution role.

1. Log in to your AWS account (the same account your bucket and agent are in).
2. Browse to the IAM dashboard.
3. In the left sidebar, click Roles.
4. Click Create Role.
5. On the Select trusted entity page:
   1. Select AWS Service.
   2. Select the Elastic Container Service.
   3. Select Elastic Container Service Task.
6. Click Next.
7. Click Create Policy. This will open a new page.
8. Choose the JSON tab and enter your policy.
   • We recommend using the provided policies on this page when following the recommended AWS installation. Ensure values in the "Resources" sections of the policy are completed with your own resource names.
   • Users who choose to follow a custom installation process should be aware of the permissions and resources required. See the actions subsection below for required permissions.
9. Click Next: Tags → Next: Review.
10. Give the policy a name and then click Create policy.
11. Return to your IAM role creation page, refresh the policies list and search for your new policy.
12. Review the policy. Note that we are prescribing two policies on this page but each policy must belong to a separate IAM role.
13. Click Next.
14. Give your new IAM role a Role name.
15. Click Create role.

---

Task execution IAM role

A basic template requires users to have an IAM role configured for task execution, with permissions to pull from ECR public repositories. You should know the ARN for this IAM role, as it's required in the ExecutionRoleArn field during stack creation.

A sample policy is provided below. You'll need to replace the ARN with your own. In some cases, AWS might choose to create a task execution role for you. This can be edited with the below if required.

{
"Version": "2012-10-17",
"Statement": [
     {
         "Action": [
             "ecr-public:GetAuthorizationToken",
             "sts:GetServiceBearerToken",
             "ecr:GetAuthorizationToken",
             "ecr:BatchCheckLayerAvailability",
             "ecr:GetDownloadUrlForLayer",
             "ecr:BatchGetImage",
             "logs:CreateLogStream",
             "logs:PutLogEvents"
           ],
    "Effect": "Allow",
    "Resource": "*",
    "Sid": "ECRAndCloudWatch"
    }
  ]
}

---

Task IAM role

The recommended IAM task role has the access to:

• S3 buckets for data staging.
  • Note that this is not the same as giving the bucket itself permissions, which is covered in the S3 Buckets topic.
• Secrets Manager secrets.
  • Platform keys
  • Database passwords

Edit the below policy to include your own resource names (ARN) in the "Resource" fields.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:s3:::bucket-name",
      "Sid": "S3List"
    },
    {
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:GetObjectAcl",
        "s3:DeleteObject"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:s3:::bucket-name/*",
      "Sid": "S3Use"
    },
    {
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:ListSecrets"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:secretsmanager:eu-west-1:0000000000:platform-key-name",
      "Sid": "SecretsManagerPerms"
    },
    {
      "Action": [
        "ecs:ListTasks",
        "ecs:ListServices",
        "ecs:DescribeContainerInstances",
        "ecs:DescribeServices",
        "ecs:DescribeTasks",
        "ecs:DescribeTaskDefinition",
        "ec2:DescribeInstances"
      ],
      "Sid": "",
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

---

Actions Summary

Task Execution Role

• ecr-public:GetAuthorizationToken
• sts:GetServiceBearerToken
• ecr:GetAuthorizationToken
• ecr:BatchCheckLayerAvailability
• ecr:GetDownloadUrlForLayer
• ecr:BatchGetImage
• logs:CreateLogStream
• logs:PutLogEvents

Task Role

• s3:ListBucket
• s3:GetBucketLocation
• s3:PutObject
• s3:PutObjectAcl
• s3:GetObject
• s3:GetObjectAcl
• s3:DeleteObject
• secretsmanager:GetSecretValue
• secretsmanager:ListSecrets