Introduction

For ECS on Fargate, the execution role and the task role solve different problems, and mixing them up is a common cause of confusing Terraform and ECS errors. The execution role is used by ECS itself to pull images and publish logs. The task role is assumed by the application code inside the running container. If a Fargate task definition is “requesting execution role,” the usual fix is to define execution_role_arn correctly and attach the expected permissions.

What The Execution Role Is For

The execution role is used by the ECS agent and platform on your behalf for operations such as:

• pulling container images from ECR,
• sending container logs to CloudWatch,
• retrieving secrets or parameters referenced in task startup configuration.

This is not the same as the role your application uses when it calls AWS APIs at runtime.

The Terraform Field You Need

In Terraform, the ECS task definition usually looks like this:

1resource "aws_ecs_task_definition" "app" {
2  family                   = "sample-app"
3  requires_compatibilities = ["FARGATE"]
4  network_mode             = "awsvpc"
5  cpu                      = "256"
6  memory                   = "512"
7  execution_role_arn       = aws_iam_role.ecs_execution_role.arn
8  task_role_arn            = aws_iam_role.app_task_role.arn
9
10  container_definitions = jsonencode([
11    {
12      name      = "app"
13      image     = "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest"
14      essential = true
15      logConfiguration = {
16        logDriver = "awslogs"
17        options = {
18          awslogs-group         = "/ecs/sample-app"
19          awslogs-region        = "us-east-1"
20          awslogs-stream-prefix = "ecs"
21        }
22      }
23    }
24  ])
25}

If you omit execution_role_arn in cases where Fargate needs it, ECS may reject the task definition or fail to start the task properly.

Create The Execution Role In Terraform

You need an IAM role that ECS tasks can assume.

1resource "aws_iam_role" "ecs_execution_role" {
2  name = "ecsTaskExecutionRole"
3
4  assume_role_policy = jsonencode({
5    Version = "2012-10-17"
6    Statement = [
7      {
8        Effect = "Allow"
9        Principal = {
10          Service = "ecs-tasks.amazonaws.com"
11        }
12        Action = "sts:AssumeRole"
13      }
14    ]
15  })
16}

Then attach the standard execution policy.

1resource "aws_iam_role_policy_attachment" "ecs_execution_attach" {
2  role       = aws_iam_role.ecs_execution_role.name
3  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
4}

That managed policy covers the common baseline for ECR pulls and CloudWatch Logs.

Execution Role Versus Task Role

This distinction is worth repeating because it causes a lot of confusion.

• 'execution_role_arn: used by ECS and Fargate infrastructure during task startup and platform-managed operations.'
• 'task_role_arn: used by the application code inside the container after it is running.'

If your container needs to read from S3 at runtime, that permission belongs on the task role, not on the execution role. If the task needs to pull from ECR, that belongs on the execution role.

Why Fargate Commonly Needs It

Fargate abstracts away the host instance, so platform-managed steps such as image retrieval and log initialization rely heavily on that execution role. That is why Fargate tasks often surface this configuration issue quickly.

In older examples or EC2-backed ECS examples, the role separation may look less obvious, which is why copied configurations often break when moved to Fargate.

A Good Validation Checklist

If task definition registration or startup is failing, check:

• 'execution_role_arn exists,'
• the role trust policy allows ecs-tasks.amazonaws.com,
• the managed execution policy is attached,
• 'task_role_arn is not being confused with the execution role,'
• referenced logs, secrets, and image sources match the permissions actually granted.

That checklist catches most role-related issues.

Common Pitfalls

• Using task_role_arn and thinking it replaces execution_role_arn.
• Creating the role but forgetting the ecs-tasks.amazonaws.com trust relationship.
• Forgetting the standard managed execution policy attachment.
• Putting application runtime permissions on the execution role instead of the task role.
• Reusing an EC2 ECS example and assuming the same role expectations apply cleanly to Fargate.

Summary

• Fargate task definitions often need an execution_role_arn so ECS can pull images and publish logs.
• The execution role is different from the application’s task role.
• In Terraform, define the role, trust policy, and policy attachment explicitly.
• Use the execution role for ECS platform operations and the task role for app AWS API access.
• When ECS complains about execution role requirements, the fix is usually role definition, trust, or permission alignment.