Health Checks
ECS uses container and load balancer health checks to keep only healthy tasks in service.
ECS watches health from two angles:
- Container health check — a command run inside the container (
healthCheckin the task definition). - Load balancer health check — the target group probing an HTTP path.
If a task is unhealthy, the service stops it and launches a replacement. During deploys, a failing health check can automatically stop the rollout.
Example
{
"containerDefinitions": [
{
"name": "app",
"image": "app:1",
"healthCheck": {
"command": [
"CMD-SHELL",
"curl -f http://localhost:8080/health || exit 1"
],
"interval": 30,
"timeout": 5,
"retries": 3,
"startPeriod": 60
}
}
]
}When to use it
- A team configures a container health check that runs every 30 seconds so ECS replaces any task whose health check fails three times in a row.
- An SRE tunes the ALB health check timeout to 3 seconds and the interval to 10 seconds so unhealthy tasks are removed from the target group within 30 seconds.
- A developer adds a /health endpoint to their API container that returns 200 only when the database connection pool is healthy, giving the ALB a meaningful signal.
More examples
Container Health Check in Task Definition
Defines a container health check that polls /health every 30 seconds, with a 60-second grace period on startup and 3 failures before the container is marked unhealthy.
{
"name": "api",
"image": "my-api:latest",
"healthCheck": {
"command": ["CMD-SHELL", "curl -sf http://localhost:8080/health || exit 1"],
"interval": 30,
"timeout": 5,
"retries": 3,
"startPeriod": 60
}
}ALB Health Check Configuration
Configures the ALB target group to check /health every 10 seconds and mark a task unhealthy after 3 consecutive failures — removing it from rotation in about 30 seconds.
aws elbv2 modify-target-group \
--target-group-arn arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/api-tg/abc \
--health-check-path /health \
--health-check-interval-seconds 10 \
--health-check-timeout-seconds 3 \
--healthy-threshold-count 2 \
--unhealthy-threshold-count 3Describe Task Health and Stop Reason
Retrieves the health status and stop reason for each container in a task, useful for diagnosing why ECS stopped and replaced a task.
aws ecs describe-tasks \
--cluster prod \
--tasks arn:aws:ecs:us-east-1:123456789012:task/prod/abc123 \
--query 'tasks[0].containers[*].{name:name,health:healthStatus,lastStatus:lastStatus,reason:reason}'
Discussion