ECS Task

AWS Cloud Engineering hub

A running instance of a Task Definition in Amazon ECS — equivalent to a running Docker container. Tasks are managed by ECS Services which keep a desired number of tasks running and replace failed ones automatically.

An ECS Task is a running instance of a Task Definition — the ECS equivalent of executing docker run. It is the smallest unit of work in ECS. A Task Definition is the saved blueprint. A Task is one live container (or group of containers) running from that blueprint.

Task Definition — The Blueprint

A Task Definition defines everything about how your container runs:

TEXT

Container image URI:    which Docker image to pull from ECR or Docker Hub
CPU and Memory:         reserved resources for this task (e.g. 0.5 vCPU, 1 GB)
Port mappings:          container port to expose (e.g. 8080)
Environment variables:  configuration the app needs at runtime
Execution Role:         IAM role for ECS Agent (pull image, write logs)
Task Role:              IAM role for your application code (read S3, write DynamoDB)
Log configuration:      where container stdout/stderr goes (CloudWatch Logs)
Health check:           command to verify the container is working
Volumes:                EFS mounts for persistent shared storage

Two IAM Roles — Completely Separate Purposes

This is the most commonly confused concept in ECS:

◈ DIAGRAM

ECS Execution Role:
  Used by the ECS Agent (the ECS infrastructure layer)
  Pulls the container image from ECR
  Sends container logs to CloudWatch Logs
  Fetches secrets from SSM Parameter Store at task startup
 
ECS Task Role:
  Used by YOUR APPLICATION CODE running inside the container
  Read files from S3
  Write messages to SQS
  Query DynamoDB
  Call Secrets Manager at runtime
 
EC2 Instance (runs on this)
├── Execution Role → ECS Agent → ECR, CloudWatch, SSM
└── Container App (your code)
      └── Task Role → S3, DynamoDB, SQS

Launch Types

TEXT

Fargate:  AWS manages all compute. You define CPU and memory. No EC2 to see or manage.
          Pay per task second. Scale by adjusting task count.
EC2:      You provision and manage EC2 instances. ECS places containers on them.
          Pay for EC2 instances whether running containers or not.

ECS Service — Keeps Tasks Running

An ECS Service maintains a desired count of running tasks:

◈ DIAGRAM

Service: desired 3 tasks
Task crashes → Service detects → launches replacement automatically
New deployment → rolling update → replace tasks one at a time → zero downtime
ALB integration → new tasks register automatically → old tasks drain connections before termination

Task Placement (EC2 Launch Type)

ECS must decide which EC2 instance to place each task on:

TEXT

Spread: distribute tasks across multiple instances and AZs (best for HA)
Binpack: fill one instance before using another (best for cost efficiency)
Random: assign randomly across available instances

Common Mistake
When a Fargate task stops immediately after starting, the cause is almost always visible in CloudWatch Logs. Container stdout and stderr are sent there if you configured the awslogs log driver (which the console does by default). Check logs before spending time on network or IAM debugging — the exit reason is almost always one line in the logs.

Frequently Asked Questions

What's the relationship between an ECS Task, a Task Definition, and a Service?

A Task Definition is a JSON blueprint specifying container images, CPU/memory, networking, and IAM roles — analogous to a docker-compose file. A Task is one running instantiation of that definition, comparable to a running container (or group of containers sharing a network namespace). A Service wraps tasks with a desired count, restarting failed tasks and optionally attaching a load balancer, similar in spirit to a Kubernetes Deployment.

What's a common mistake when sizing CPU and memory for an ECS task?

Setting task-level CPU/memory too tight causes OOM kills or throttling under load spikes, since ECS enforces hard memory limits (the container is killed, not throttled, when it exceeds the limit). A common practice is to size for the 95th-percentile load rather than average, and to distinguish container-level limits from task-level limits — a task can define an overall ceiling while individual containers within it have their own soft/hard limits.