Amazon Elastic Container Service (ECS) is a fully managed container orchestration service. Run Docker containers on Fargate (serverless) or self-managed EC2 instances with deep AWS integration.
Core Concepts
- Cluster — logical grouping of tasks and services
- Task Definition — blueprint for containers (image, CPU, memory, ports, env vars)
- Task — a running instance of a task definition
- Service — maintains desired count of tasks, integrates with ALB
- Fargate — serverless compute for containers, no EC2 management
- ECR — Elastic Container Registry for storing Docker images
Cluster Setup
bash
# Create a Fargate cluster
aws ecs create-cluster --cluster-name app-prod --capacity-providers FARGATE FARGATE_SPOT
Task Definitions
json
// task-definition.json — web application task
{
"family": "web-app",
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
"cpu": "512",
"memory": "1024",
"executionRoleArn": "arn:aws:iam::123456789:role/ecsTaskExecutionRole",
"taskRoleArn": "arn:aws:iam::123456789:role/ecsTaskRole",
"containerDefinitions": [
{
"name": "web",
"image": "123456789.dkr.ecr.us-east-1.amazonaws.com/web-app:latest",
"portMappings": [{"containerPort": 8080, "protocol": "tcp"}],
"environment": [
{"name": "NODE_ENV", "value": "production"}
],
"secrets": [
{"name": "DATABASE_URL", "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789:secret:db-url"}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/web-app",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "web"
}
},
"healthCheck": {
"command": ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"],
"interval": 30,
"timeout": 5,
"retries": 3
}
}
]
}
bash
# Register task definition
aws ecs register-task-definition --cli-input-json file://task-definition.json
Services
bash
# Create a service with ALB and Fargate
aws ecs create-service \
--cluster app-prod \
--service-name web-app \
--task-definition web-app:1 \
--desired-count 3 \
--launch-type FARGATE \
--network-configuration '{
"awsvpcConfiguration": {
"subnets": ["subnet-aaa", "subnet-bbb"],
"securityGroups": ["sg-0123456789abcdef0"],
"assignPublicIp": "DISABLED"
}
}' \
--load-balancers '[{
"targetGroupArn": "arn:aws:elasticloadbalancing:us-east-1:123456789:targetgroup/web-tg/abc123",
"containerName": "web",
"containerPort": 8080
}]' \
--deployment-configuration '{
"maximumPercent": 200,
"minimumHealthyPercent": 100,
"deploymentCircuitBreaker": {"enable": true, "rollback": true}
}'
bash
# Update service (deploy new image)
aws ecs update-service \
--cluster app-prod \
--service web-app \
--task-definition web-app:2 \
--force-new-deployment
bash
# Scale service
aws ecs update-service \
--cluster app-prod \
--service web-app \
--desired-count 5
Auto Scaling
bash
# Register scalable target
aws application-autoscaling register-scalable-target \
--service-namespace ecs \
--resource-id service/app-prod/web-app \
--scalable-dimension ecs:service:DesiredCount \
--min-capacity 2 \
--max-capacity 20
bash
# Target tracking on CPU
aws application-autoscaling put-scaling-policy \
--service-namespace ecs \
--resource-id service/app-prod/web-app \
--scalable-dimension ecs:service:DesiredCount \
--policy-name cpu-scaling \
--policy-type TargetTrackingScaling \
--target-tracking-scaling-policy-configuration '{
"PredefinedMetricSpecification": {"PredefinedMetricType": "ECSServiceAverageCPUUtilization"},
"TargetValue": 70.0,
"ScaleInCooldown": 300,
"ScaleOutCooldown": 60
}'
ECR (Container Registry)
bash
# Create repository
aws ecr create-repository --repository-name web-app --image-scanning-configuration scanOnPush=true
bash
# Login, build, push
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com
docker build -t web-app .
docker tag web-app:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/web-app:latest
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/web-app:latest
Running One-Off Tasks
bash
# Run a migration task
aws ecs run-task \
--cluster app-prod \
--task-definition db-migrate:1 \
--launch-type FARGATE \
--network-configuration '{
"awsvpcConfiguration": {
"subnets": ["subnet-aaa"],
"securityGroups": ["sg-0123456789abcdef0"],
"assignPublicIp": "DISABLED"
}
}' \
--overrides '{
"containerOverrides": [{"name": "migrate", "command": ["npm", "run", "migrate"]}]
}'
Monitoring
bash
# List running tasks
aws ecs list-tasks --cluster app-prod --service-name web-app --desired-status RUNNING
bash
# View task logs
aws logs tail /ecs/web-app --follow --since 1h
Best Practices
- Use Fargate for most workloads to eliminate instance management
- Store secrets in Secrets Manager or Parameter Store, not environment variables
- Enable deployment circuit breaker to auto-rollback failed deployments
- Use awslogs driver for centralized logging in CloudWatch
- Set health checks in both the task definition and target group
- Use Fargate Spot for non-critical background workers (up to 70% savings)
- Pin image tags in production; avoid
latestfor reproducibility