Documented steps

Register the task definition first (RegisterTaskDefinition) and note its family:revision.
Set the deployment controller explicitly: --deployment-controller type=ECS (also the default when omitted).
Choose deploymentConfiguration limits: maximumPercent (upper bound on total tasks during rollout, rounded down) and minimumHealthyPercent (lower bound on healthy tasks, rounded up) — e.g. maximumPercent=200,minimumHealthyPercent=100 for a zero-downtime batch swap.
Enable the circuit breaker inside the same deploymentConfiguration: deploymentCircuitBreaker={enable=true,rollback=true} so failed rollouts auto-revert to the last COMPLETED deployment.
If fronting the service with a load balancer, pass --load-balancer targetGroupArn=...,containerName=...,containerPort=... and set --health-check-grace-period-seconds (default 0) long enough to cover slow app startup.
Run: aws ecs create-service --cluster my-cluster --service-name my-service --task-definition my-app:3 --desired-count 3 --launch-type FARGATE --deployment-controller type=ECS --deployment-configuration "maximumPercent=200,minimumHealthyPercent=100,deploymentCircuitBreaker={enable=true,rollback=true}" --health-check-grace-period-seconds 60 --network-configuration "awsvpcConfiguration={subnets=[subnet-1,subnet-2],securityGroups=[sg-1],assignPublicIp=ENABLED}"
Poll rollout progress: aws ecs describe-services --cluster my-cluster --services my-service --query 'services[0].deployments[].{status:status,rolloutState:rolloutState,rolloutStateReason:rolloutStateReason,running:runningCount,desired:desiredCount}' — rolloutState is IN_PROGRESS, COMPLETED, or FAILED.
Or block synchronously: aws ecs wait services-stable --cluster my-cluster --services my-service, which polls DescribeServices every 15 seconds for up to 40 attempts (~10 minutes) and succeeds once exactly one deployment remains with runningCount == desiredCount.
If rolloutState becomes FAILED with rollback enabled, ECS automatically starts a new deployment targeting the last COMPLETED task definition — verify via deployments[].taskDefinition after the FAILED event.
Optionally subscribe to the EventBridge event SERVICE_DEPLOYMENT_FAILED for asynchronous notification instead of polling.
Official docs: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html | https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html | https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Deployment.html | https://docs.aws.amazon.com/cli/latest/reference/ecs/wait/services-stable.html

Known gotchas

rolloutState/rolloutStateReason are only populated for services using the ECS rolling-update deployment controller that are not behind a Classic Load Balancer — CODE_DEPLOY/EXTERNAL controllers or CLB-fronted services won't return them.
The circuit breaker is only supported with deploymentController type=ECS; it cannot be combined with CODE_DEPLOY or EXTERNAL.
If there is no prior COMPLETED deployment to roll back to (e.g. the very first deployment of a brand-new service fails), the circuit breaker stalls with no new tasks launched instead of rolling back — you must intervene manually.
Setting minimumHealthyPercent below 100 lets the scheduler stop old healthy tasks before new tasks are confirmed healthy, transiently reducing capacity during the rollout.
healthCheckGracePeriodSeconds defaults to 0; with a load-balanced service and a slow-starting container, ECS/ELB may mark tasks unhealthy and cycle them before the app is ready, producing repeated 'Task failed ELB health checks' stopped-task events.
aws ecs wait services-stable gives up (exit code 255) after 40 attempts at 15-second intervals (~10 minutes); a legitimately slow rollout on a large service can trip this client-side timeout even though the deployment eventually succeeds.
The scheduler must be able to start or stop at least one task given your maximumPercent/minimumHealthyPercent/desiredCount combination — impossible combinations surface as service event messages rather than a hard API error at CreateService time.
Circuit breaker failure detection has two stages: tasks failing to reach RUNNING, and tasks failing load balancer/Cloud Map/container health checks after reaching RUNNING — both count toward the failure threshold that triggers rollback.

Create an ECS service with the rolling (ECS) deployment controller, deployment circuit breaker with automatic rollback, and poll its rollout status

Documented steps

Known gotchas

Related routes

Give your agent this knowledge — and 16,300+ more routes

Need this verified for your stack — or a route we don't have yet?