ECS Task Definitions

A task definition is the heart of Amazon ECS. It is a JSON document that acts as a blueprint for running containers — describing which images to use, how much CPU and memory to allocate, what ports to expose, how to handle logging, and much more. Understanding task definitions thoroughly is essential for running containers on ECS effectively.

---

Task Definition Structure

A task definition contains two layers of configuration:

1. Task-level settings — apply to the entire task (all containers in it)
2. Container definitions — configure each individual container within the task

{
  "family": "my-web-app",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::123456789012:role/myAppTaskRole",
  "containerDefinitions": [
    {
      "name": "web",
      "image": "123456789012.dkr.ecr.eu-west-2.amazonaws.com/my-web-app:v1.0.0",
      "portMappings": [
        { "containerPort": 3000, "protocol": "tcp" }
      ],
      "essential": true,
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/my-web-app",
          "awslogs-region": "eu-west-2",
          "awslogs-stream-prefix": "web"
        }
      }
    }
  ]
}

---

Task-Level Settings

Family

The family is the name of your task definition. ECS uses it to group revisions — each time you update a task definition, a new revision is created (e.g. my-web-app:1, my-web-app:2, my-web-app:3).

Network Mode

Mode	Description	Use With
awsvpc	Each task gets its own Elastic Network Interface (ENI) with a private IP	Fargate (required), EC2
bridge	Uses Docker's built-in bridge networking	EC2 only
host	Container shares the host's network namespace	EC2 only
none	No networking	Special cases

awsvpc is the recommended mode and is required for Fargate. It gives each task its own security group and simplifies network configuration.

CPU and Memory

For Fargate, CPU and memory must be set at the task level using specific combinations:

CPU (units)	Memory (MiB) Options
256 (0.25 vCPU)	512, 1024, 2048
512 (0.5 vCPU)	1024 – 4096 (in 1024 increments)
1024 (1 vCPU)	2048 – 8192 (in 1024 increments)
2048 (2 vCPU)	4096 – 16384 (in 1024 increments)
4096 (4 vCPU)	8192 – 30720 (in 1024 increments)
8192 (8 vCPU)	16384 – 61440 (in 4096 increments)
16384 (16 vCPU)	32768 – 122880 (in 8192 increments)

For EC2 launch type, you can set CPU and memory at the container level instead.

---

IAM Roles

Task definitions reference two types of IAM roles:

Execution Role (executionRoleArn)

Used by the ECS agent to perform actions on your behalf:

• Pull container images from ECR
• Send logs to CloudWatch Logs
• Retrieve secrets from AWS Secrets Manager or SSM Parameter Store

The AWS-managed policy AmazonECSTaskExecutionRolePolicy covers the most common permissions.

Task Role (taskRoleArn)

Used by the application code running inside the container:

• Read from or write to S3
• Publish messages to SNS or SQS
• Access DynamoDB tables
• Call any AWS API your application needs

This follows the principle of least privilege — each application gets only the permissions it requires.

---

Container Definitions

Each container definition includes:

Essential Fields

Field	Description
name	A unique name for the container within the task
image	The Docker image to use (e.g. ECR URI with tag)
essential	If true and this container stops, the entire task stops

Port Mappings