Safer Deploys: Circuit Breaker & Health Checks
Let ECS catch a bad rollout for you with the deployment circuit breaker, honest health checks, and a sensible start period.
The scariest deploys are the silent ones — where ECS happily replaces every healthy task with a broken revision because nothing told it to stop. The good news is that ECS has a built-in safety net; you just have to turn it on and feed it honest signals.
Turn on the deployment circuit breaker
With deploymentCircuitBreaker enabled and rollback set to true, ECS watches how many new tasks fail to reach a healthy, stable state. If too many fail, it halts the deployment and automatically rolls back to the last known-good revision. This one setting has saved more 2am pages than almost anything else I configure.
Make health checks tell the truth
A circuit breaker is only as good as your health check. A /health endpoint that returns 200 the instant the process starts — before the DB pool or cache is ready — will let a broken deploy sail through. Have the check verify the dependencies the app actually needs to serve traffic.
Give slow starters a grace period
Use startPeriod on the container health check (and a matching health-check grace period on the service) so a JVM or Rails app that takes 40 seconds to warm up is not killed before it ever gets a chance.
A deploy strategy without automatic rollback is just a faster way to take down production. Enable the circuit breaker on every service.
Example
# Enable the deployment circuit breaker with automatic rollback,
# and give slow-starting tasks time before health checks count.
aws ecs update-service \
--cluster prod --service web \
--task-definition web:43 \
--health-check-grace-period-seconds 60 \
--deployment-configuration '{
"deploymentCircuitBreaker": { "enable": true, "rollback": true },
"minimumHealthyPercent": 100,
"maximumPercent": 200
}'When to use it
- A team enables the deployment circuit breaker with rollback so a bad image that causes all tasks to crash-loop is automatically reverted without an on-call page.
- An SRE sets minimumHealthyPercent to 100 so a deployment never reduces live capacity — ECS must bring up new tasks before it terminates old ones.
- A developer adds a /health endpoint that returns 503 while the application is warming up so ECS does not send traffic to tasks before they are ready.
More examples
Enable Circuit Breaker with Auto-Rollback
Enables the deployment circuit breaker with rollback and ensures ECS always keeps 100% of healthy tasks while deploying, so capacity is never reduced.
aws ecs update-service \
--cluster prod \
--service api \
--deployment-configuration \
'deploymentCircuitBreaker={enable=true,rollback=true},minimumHealthyPercent=100,maximumPercent=200'Container Health Check with Start Period
Gives the container 45 seconds to start before health checks are evaluated, preventing ECS from killing a slow-starting container prematurely.
{
"name": "api",
"image": "my-api:latest",
"healthCheck": {
"command": ["CMD-SHELL", "wget -qO- http://localhost:8080/health || exit 1"],
"interval": 10,
"timeout": 3,
"retries": 3,
"startPeriod": 45
}
}Check Deployment Rollback Status
Lists all active deployments for the service and shows which ones are rolling out, rolling back, or completed — with the reason for any rollback.
aws ecs describe-services \
--cluster prod \
--services api \
--query 'services[0].deployments[*].{id:id,status:status,taskDef:taskDefinition,reason:rolloutStateReason}'
Discussion