aws ecs update-service: Deploy to ECS in CI

Roll an ECS service to a new task definition or force a fresh deployment.

aws ecs update-service changes a service to a new task definition revision (or forces a redeploy of the current one) and triggers a rolling deployment. It is the final step of most ECS/Fargate CI pipelines after building and pushing an image.

Common flags

--cluster - the ECS cluster name (required)
--service - the service to update (required)
--task-definition family:revision - point the service at a new revision
--force-new-deployment - redeploy even with no task-def change (pull :latest)
--desired-count - change the number of running tasks

Example in CI

Deploy a freshly registered task definition revision.

shell

aws ecs update-service --cluster prod --service web --task-definition web:${TASK_REVISION} --force-new-deployment

Common errors in CI

An error occurred (ServiceNotFoundException) - service or cluster name is wrong
An error occurred (InvalidParameterException) - task definition revision does not exist
An error occurred (AccessDeniedException) - role lacks ecs:UpdateService
An error occurred (ClusterNotFoundException) - cluster ARN/name typo

Key takeaways

update-service rolls a service to a new task definition revision.
--force-new-deployment redeploys without a task-def change to pull :latest.
It returns immediately; poll describe-services to confirm the rollout finished.