CloudConsole

aws ecs update-service

Updated 16 November 2026 · How we write and check guides

Short answer

aws ecs update-service --cluster my-cluster --service my-service --force-new-deployment restarts every task in a service with the current task definition, which also re-pulls a mutable image tag such as latest. Pass --task-definition family:revision to roll out a new version, or --desired-count to scale, then run aws ecs wait services-stable.

Terminal running aws ecs update-service --cluster prod --service orders-api…
A worked example from this page. Copy commands from the text below, not from the image.

What the command does

update-service changes a running ECS service and, when the change affects tasks, starts a new deployment. With the default rolling update, ECS starts new tasks and drains old ones within the limits set by minimumHealthyPercent and maximumPercent, waiting for load balancer health checks where configured.

It returns the updated service description immediately; the deployment itself takes minutes. Watch it with describe-services or a waiter.

Syntax

aws ecs update-service --cluster my-cluster --service my-service \
  [--task-definition orders-api:42] \
  [--desired-count 4] \
  [--force-new-deployment] \
  [--deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true},maximumPercent=200,minimumHealthyPercent=100"] \
  [--enable-execute-command] \
  [--health-check-grace-period-seconds 60]

If you leave out --cluster, ECS uses the cluster called default, which produces a confusing ServiceNotFoundException.

Worked examples

Restart all tasks (new containers, same task definition):

aws ecs update-service --cluster prod --service orders-api --force-new-deployment \
  --query "service.deployments[0].[id,rolloutState]" --output text
aws ecs wait services-stable --cluster prod --services orders-api

Deploy a new task definition revision:

aws ecs update-service --cluster prod --service orders-api --task-definition orders-api:43

Passing only the family (orders-api) uses its latest ACTIVE revision.

Scale out or in:

aws ecs update-service --cluster prod --service orders-api --desired-count 6

Scale to zero to stop a non-production service overnight:

aws ecs update-service --cluster staging --service orders-api --desired-count 0

Turn on automatic rollback when tasks keep failing to become healthy:

aws ecs update-service --cluster prod --service orders-api \
  --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true},maximumPercent=200,minimumHealthyPercent=100"

Enable ECS Exec; it only applies to tasks started afterwards, so force a deployment in the same call:

aws ecs update-service --cluster prod --service orders-api \
  --enable-execute-command --force-new-deployment

Watching the rollout

aws ecs describe-services --cluster prod --services orders-api \
  --query "services[0].deployments[].[status,taskDefinition,rolloutState,runningCount,desiredCount]" \
  --output table
rolloutStateMeaning
IN_PROGRESSNew tasks starting or old ones draining.
COMPLETEDThe PRIMARY deployment reached steady state.
FAILEDThe circuit breaker tripped; with rollback on, ECS redeploys the last completed revision.

The waiter gives up after about ten minutes and exits non-zero, which does not mean the deployment failed; check the state above.

Gotchas

  • Auto scaling overrides desired count. If the service has an Application Auto Scaling target, a manual --desired-count can be changed back by the next scaling action, and is clamped by the target's minimum and maximum.
  • Mutable tags. Force-new-deployment re-pulls :latest, so it can deploy code you did not intend. Pin image digests or unique tags in task definitions.
  • Stuck deployments usually mean new tasks never pass health checks. Read services[0].events and the stopped tasks' stoppedReason.
  • Some settings need a new deployment to take effect on existing tasks, such as ECS Exec and network configuration.

Questions

How do I force a new deployment of an ECS service?

aws ecs update-service --cluster my-cluster --service my-service --force-new-deployment, then aws ecs wait services-stable to wait for it.

How do I update the image of an ECS service from the CLI?

Register a new task definition revision with the new image, then run update-service --task-definition with that revision.

How do I change the desired count of an ECS service?

Use update-service --desired-count. If the service uses auto scaling, adjust the scalable target's minimum and maximum instead or your change may be reverted.

When this happens away from your desk

Restarting a service is one of the most common on-call actions, and one you want to get right first time. CloudConsole, a phone app for AWS, is built to show service health, deployments and alarms on a phone, with production guardrails.

About the app → · Download on the App Store

Sources