Deep Dive into ECS Task Definitions: The Blueprint of Your Containers

A task definition is a blueprint for your application. It is a text file in JSON format that describes the parameters and one or more containers that form your application.

>> The following are some of the parameters that you can specify in a task definition:

The launch type to use, which determines the infrastructure that your tasks are hosted on

The Docker image to use with each container in your task

How much CPU and memory to use with each task or each container within a task

The memory and CPU requirements

The operating system of the container that the task runs on

The Docker networking mode to use for the containers in your task

The logging configuration to use for your tasks

Whether the task continues to run if the container finishes or fails

The command that the container runs when it's started

Any data volumes that are used with the containers in the task

The IAM role that your tasks use

What is a Task Definition?
A task definition is a JSON file (or equivalent when using AWS Console, SDK, or CDK) that describes one or more containers needed to run your application.

You can think of it as:

A recipe that ECS uses to launch tasks.

It defines the container configuration (image, resources, ports, etc.).

It can include multiple containers if your app needs them (e.g., web + sidecar).

Key Parameters in ECS Task Definitions:
Let’s break down the important fields you’ll encounter:

1. Container Definitions:

The heart of a task definition is the containerDefinitions section. Each container definition includes settings for a single container.

Key parameters include:

image → The Docker image to run (e.g., nginx:latest or 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:1.0).

name → Logical name for the container inside ECS.

essential → Boolean that tells ECS if this container must run for the task to be healthy.

2. CPU and Memory:

You can define CPU and memory at both task level and container level.

Task-level (cpu, memory): Defines the total resources for the entire task.

Container-level (cpu, memoryReservation, memory): Defines how much of those resources each container gets.

"cpu"
:

256
,

"memory"
:

512

3. Environment Variables
Used to configure applications without hardcoding values.

"environment": [
  { "name": "ENV", "value": "production" },
  { "name": "DEBUG", "value": "false" }
]

4. Port Mappings

Defines how container ports are exposed.

"portMappings": [
  { "containerPort": 80, "hostPort": 80, "protocol": "tcp" }
]

containerPort: Inside container.

hostPort: Exposed on host (for Fargate, usually matches containerPort).

5. Volumes and Mount Points

If your app needs persistent storage or shared data between containers.

Volumes are defined at the task level.

Mount points connect those volumes to a container.

"mountPoints": [
  {
    "sourceVolume": "app-storage",
    "containerPath": "/data"
  }
]

6. Logging

ECS integrates seamlessly with Amazon CloudWatch Logs.

"logConfiguration": {
  "logDriver": "awslogs",
  "options": {
    "awslogs-group": "/ecs/my-app",
    "awslogs-region": "us-east-1",
    "awslogs-stream-prefix": "ecs"
  }
}

7. Command and EntryPoint

Overrides the default behavior of the Docker image.

entryPoint → Overrides the ENTRYPOINT in Dockerfile.

command → Overrides the CMD in Dockerfile.

"command": ["node", "server.js"]

8. Networking Mode

Specifies how containers in a task communicate.

bridge → Default for EC2 (Docker bridge network).

awsvpc → Each task gets its own ENI (used in Fargate).

host → Containers share host networking.

9. IAM Roles

You can assign task roles to containers for AWS permissions.

"taskRoleArn": "arn:aws:iam::123456789:role/ecsTaskExecutionRole"

Putting It All Together: Example Task Definition

Here’s a simplified JSON snippet:

{
  "family": "my-app",
  "cpu": "256",
  "memory": "512",
  "networkMode": "awsvpc",
  "containerDefinitions": [
    {
      "name": "web",
      "image": "nginx:latest",
      "cpu": 256,
      "memory": 512,
      "essential": true,
      "portMappings": [
        { "containerPort": 80, "hostPort": 80 }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/my-app",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

Best Practices for Task Definitions

✅ Use task roles for AWS service access (never hardcode credentials).

✅ Keep container images small for faster startup.

✅ Define resource limits to avoid noisy-neighbor issues.

✅ Centralize logs with CloudWatch.

✅ Use secrets managers for sensitive data.