Skip to content

IAM Roles

When creating resources in AWS, they require permissions to interact with one another. Specifically, the agent requires two IAM Roles that the user should create:

  • Task Role
  • Task Execution Role

If you are using the Advanced CloudFormation Template to install the agent, these IAM Roles are created for you and require no manipulation (although does require you to know the ARN of your Platform Key and database passwords secrets during installation).

This article outlines the process and policies to create these roles and the resources they should have access to.

:::info{title='Note'} It is also necessary to add a policy to the S3 Bucket used for staging. This is discussed in the S3 Buckets article and can be done independently of these instructions. :::

Creating IAM Roles

Note that this process must be done 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, or will be, in)
  2. Browse to the IAM and Access Management dashboard
  3. 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.

Policy Creation

  1. 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 install process should be aware of the permissions and resources required. See the actions subsection below for required permissions
  2. Click Next: Tags → Next: Review
  3. Give the policy a name and then click Create policy

Finalizing IAM Roles

  1. Return to your IAM Role creation page, refresh the policies list and search for your new policy
  2. Check the policy. Note that we are prescribing two policies on this page but each most belong to a separate IAM Role.
  3. Click Next
  4. Give your new IAM Role a Role name
  5. Click Create role

Task Execution IAM Role

A basic template requires users to have a 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 is required in the ExecutionRoleArn field during stack creation.

A sample policy is provided below. Note that you will 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 permissions to: - S3 Bucket for data staging - Note that this is not the same as giving the bucket itself permissions, which is covered in the S3 Buckets article - Secrets Manager secrets for: - Platform Key - Database passwords

Important: Your are required to 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",
        "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