How Do I Set an ECS Task Role to Pull ECR Images on AWS?

Introduction

Amazon Elastic Container Service (ECS) allows you to run containerized applications on AWS. To facilitate this, ECS tasks often need to pull container images stored in Amazon Elastic Container Registry (ECR). This requires configuring an ECS task role with the necessary permissions. This guide will walk you through setting up an ECS task role to pull images from ECR.

Step-by-Step Explanation

To configure an ECS task role for pulling images from ECR, follow these steps:

Create an IAM Role: Define an IAM role that can be assumed by ECS tasks. This role needs a trust relationship allowing ECS tasks to assume it.
Attach Managed Policy: Attach the AmazonECSTaskExecutionRolePolicy managed policy to the IAM role. This policy provides the necessary permissions for ECS tasks to operate.
Create Custom ECR Policy: Define a custom inline policy that allows specific ECR actions, such as ecr:GetDownloadUrlForLayer, ecr:BatchGetImage, and ecr:BatchCheckLayerAvailability.
Attach Custom Policy: Attach the custom ECR policy to the ECS task execution role to grant permissions for pulling images.
Define ECS Task: Create an ECS task definition that specifies the execution role and includes container configurations.
Export ARNs: Export the Amazon Resource Names (ARNs) of the ECS task role and task definition for easy reference and management.

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

// Create IAM role for ECS task execution
const ecsTaskExecutionRole = new aws.iam.Role("ecs_task_execution_role", {
    name: "ecsTaskExecutionRole",
    assumeRolePolicy: JSON.stringify({
        Statement: [{
            Action: "sts:AssumeRole",
            Effect: "Allow",
            Principal: {
                Service: "ecs-tasks.amazonaws.com",
            },
        }],
        Version: "2012-10-17",
    }),
});
// Attach AmazonECSTaskExecutionRolePolicy policy to the IAM role
const ecsTaskExecutionRolePolicyAttachment = new aws.iam.RolePolicyAttachment("ecs_task_execution_role_policy_attachment", {
    role: ecsTaskExecutionRole.name,
    policyArn: "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy",
});
// Create custom inline policy to allow additional ECR actions
const ecrAccessPolicy = new aws.iam.Policy("ecr_access_policy", {
    name: "ecrAccessPolicy",
    policy: JSON.stringify({
        Statement: [{
            Action: [
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage",
                "ecr:BatchCheckLayerAvailability",
            ],
            Effect: "Allow",
            Resource: "*",
        }],
        Version: "2012-10-17",
    }),
});
// Attach custom policy to the ECS task execution role
const ecrAccessPolicyAttachment = new aws.iam.RolePolicyAttachment("ecr_access_policy_attachment", {
    role: ecsTaskExecutionRole.name,
    policyArn: ecrAccessPolicy.arn,
});
// Example ECS task definition
const exampleTask = new aws.ecs.TaskDefinition("example_task", {
    family: "exampleTaskFamily",
    networkMode: "awsvpc",
    requiresCompatibilities: ["FARGATE"],
    cpu: "256",
    memory: "512",
    executionRoleArn: ecsTaskExecutionRole.arn,
    containerDefinitions: JSON.stringify([{
        name: "example-container",
        image: "123456789012.dkr.ecr.us-west-2.amazonaws.com/example-repo:latest",
        essential: true,
        memory: 512,
        cpu: 256,
        portMappings: [{
            containerPort: 80,
            hostPort: 80,
            protocol: "tcp",
        }],
    }]),
});
export const ecsTaskExecutionRoleArn = ecsTaskExecutionRole.arn;
export const ecsTaskDefinitionArn = exampleTask.arn;

Key Points

IAM Role: Create a role for ECS tasks with a trust policy.
Managed Policy: Attach the necessary AWS managed policy for ECS task execution.
Custom Policy: Define and attach a custom policy for ECR access.
ECS Task Definition: Specify the role in your ECS task definition.
Export ARNs: Ensure ARNs are exported for easy reference.

Conclusion

By following these steps, you can successfully configure an ECS task role with the necessary permissions to pull images from ECR. This setup is crucial for ensuring that your ECS tasks can access the container images they need to run efficiently on AWS. This approach not only secures your resources but also streamlines the deployment process.

Deploy this code

Want to deploy this code? Sign up for a free Pulumi account to deploy in a few clicks.

New to Pulumi?

Want to deploy this code? Sign up with Pulumi to deploy in a few clicks.