Documented steps

Register the new task definition revision first via RegisterTaskDefinition (e.g. bump the image tag), producing family:revision such as my-app:4.
Trigger the rollout: aws ecs update-service --cluster my-cluster --service my-service --task-definition my-app:4 — ECS starts revision-4 tasks and stops revision-3 tasks per the service's existing deploymentConfiguration.
If you only changed image content behind an unchanged tag (e.g. myimage:latest), add --force-new-deployment to force a fresh rollout of the current taskDefinition.
Do not rely on --desired-count changes to trigger a rollout — changing desiredCount alone scales the service but does not start a new deployment or invoke the circuit breaker.
Watch progress: aws ecs describe-services --cluster my-cluster --services my-service --query 'services[0].deployments[].{status:status,taskDef:taskDefinition,rolloutState:rolloutState,running:runningCount,desired:desiredCount}' — look for the PRIMARY deployment growing while the ACTIVE (old) deployment's runningCount falls to zero.
Block until steady state: aws ecs wait services-stable --cluster my-cluster --services my-service (polls every 15s, up to 40 attempts / ~10 minutes).
If deploymentCircuitBreaker.rollback is enabled and rolloutState transitions to FAILED, ECS automatically issues a new deployment back to the last COMPLETED task definition — confirm deployments[0].taskDefinition reverted.
To roll back manually, call update-service again with --task-definition pointing at the previous known-good family:revision.
Verify the previous revision is still ACTIVE (not deregistered) before rolling back to it — DeregisterTaskDefinition would block reuse.
After stability, confirm application health independently (logs, target group health, metrics) since services-stable only checks task counts, not application correctness.
Official docs: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.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 | https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html

Known gotchas

If you omit the revision number in --task-definition, ECS resolves to the latest ACTIVE revision at request time — always pass an explicit family:revision for predictable, auditable rollouts.
forceNewDeployment is required to pick up a new image behind an unchanged tag (e.g. :latest); ECS does not detect image digest changes on its own.
Passing --deployment-configuration on UpdateService without also changing taskDefinition does not by itself start a new deployment.
desiredCount changes alone never trigger a new deployment or circuit-breaker evaluation — only a taskDefinition change or forceNewDeployment does.
aws ecs wait services-stable times out (exit 255) after ~10 minutes; treat a timeout as 'check manually', not as 'deployment failed'.
Automatic circuit-breaker rollback only works if there is a prior COMPLETED deployment to target; the first deployment of a new service has nothing to roll back to and will stall.
ECS API calls (DescribeServices, DescribeTasks) are subject to throttling — CI/CD polling loops should use exponential backoff rather than tight fixed-interval polling.
When stopping old tasks during a rollout, ECS sends SIGTERM and waits up to the container's stopTimeout (30s default) before SIGKILL; containers that ignore SIGTERM are hard-killed, truncating in-flight requests without graceful shutdown.

Safely roll a running ECS service to a new task definition revision with UpdateService, wait for stability, and roll back if the deployment fails

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?