Deploy from the CLI

Register a new task-definition revision and update the service to roll it out.

A code deploy to ECS is usually two commands: register a new task-definition revision pointing at the new image, then update the service to use it.

Steps

  1. Push the new image to ECR.
  2. register-task-definition with the new image tag.
  3. update-service to trigger a rolling deployment.

Example

Example · bash
# Register a new revision from a JSON file
aws ecs register-task-definition --cli-input-json file://task-def.json

# Roll it out
aws ecs update-service \
  --cluster prod --service web \
  --task-definition web \
  --force-new-deployment

# Wait until the service is stable
aws ecs wait services-stable --cluster prod --services web

When to use it

  • A CI/CD pipeline registers a new task definition revision with the latest image tag and then calls update-service to roll it out to the ECS cluster.
  • A developer writes a deploy script that uses jq to render a new task definition JSON from a template, replacing only the image tag before registration.
  • An SRE waits for the ECS service to reach steady state using the AWS CLI waiter before marking a deployment as successful in the pipeline.

More examples

Register New Revision and Update Service

Registers a new task definition revision from a JSON file and immediately points the ECS service at it to trigger a rolling deployment.

Example · bash
NEW_REV=$(aws ecs register-task-definition \
  --cli-input-json file://task-def.json \
  --query 'taskDefinition.taskDefinitionArn' --output text)

aws ecs update-service \
  --cluster prod \
  --service api \
  --task-definition "$NEW_REV"

Render Image Tag into Task Definition

Uses jq to update only the container image field in a task definition template with the current git SHA before registering the new revision.

Example · bash
SHA=$(git rev-parse --short HEAD)
REPO=123456789012.dkr.ecr.us-east-1.amazonaws.com/my-api

jq --arg img "$REPO:$SHA" \
  '.containerDefinitions[0].image = $img' \
  task-def.template.json > task-def.json

aws ecs register-task-definition --cli-input-json file://task-def.json

Wait for Service Steady State

Blocks the deploy script until ECS reports the service is stable (all desired tasks are healthy), providing a reliable deployment completion signal.

Example · bash
aws ecs wait services-stable \
  --cluster prod \
  --services api

echo "Deployment complete: service is stable"

Related

ecs rolling deploymentsecs cicd push ecr

Discussion

  • Be the first to comment on this lesson.
Deploy from the CLI — Amazon ECS | SoundsCode