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