Skip to content

Operations & Imperative Commands

While declarative configuration is preferred for managing resources, ecsctl provides powerful imperative commands for daily maintenance, debugging, and rapid deployments.

đŸšĸ Deploying Images (deploy)

Update an existing ECS service with a new container image tag. This command triggers a rolling deployment by updating the service's task definition with the new image.

ecsctl deploy <service-name> --cluster <cluster-name> --image <image-url:tag> [flags]

Basic Deploy

Deploy a new image to the default container in the task definition:

ecsctl deploy my-service --cluster my-cluster --image nginx:1.25.1

Specify a Container Name

If your task definition contains multiple containers, specify the target container using the --container flag:

ecsctl deploy my-service --cluster my-cluster --image redis:7.2-alpine --container cache

↩ī¸ Rolling Back a Deployment (rollback)

Restore the task definition used by the most recent completed deployment before the service's current task definition:

ecsctl rollback my-service --cluster my-cluster --wait

Use ecsctl describe service my-service --cluster my-cluster to review task definition revisions, deployment timestamps, and rollout reasons. Rollback supports ECS rolling deployments. Services managed by CodeDeploy or an external deployment controller must be rolled back through that controller.

📈 Scaling Services (scale)

Quickly scale the running task count of an ECS service up or down.

ecsctl scale <service-name> --cluster <cluster-name> --desired <count> [flags]

Example

Scale the desired task count to 5:

ecsctl scale my-service --cluster my-cluster --desired 5

This changes the service's desired task count. If Application Auto Scaling is also configured, its policies can change the count again as load changes.

📋 Fetching Logs (logs)

Stream or fetch CloudWatch Logs events from the containers in an ECS service. The task definition must send container logs to CloudWatch Logs, and your AWS identity must be allowed to read those log events. ecsctl gathers matching logs across tasks in the service.

ecsctl logs <service-name> --cluster <cluster-name> [flags]

Tail Logs

Fetch the last 100 log lines:

ecsctl logs my-service --cluster my-cluster --tail 100

Follow Logs

Stream logs in real-time to your terminal (similar to tail -f):

ecsctl logs my-service --cluster my-cluster --follow

đŸ’ģ Interactive Container Shell (exec)

Open an interactive bash/sh session or execute a single command inside a running task container using ECS Exec.

[!IMPORTANT] To use this command, install the AWS Session Manager Plugin locally and make sure ECS Exec is enabled for the task. Your AWS identity and the task's IAM role also need the permissions required by ECS Exec. See AWS ECS Exec prerequisites.

ecsctl exec <service-name> --cluster <cluster-name> [flags]

Interactive Shell

Open a shell session (defaults to /bin/sh or /bin/bash in the default container):

ecsctl exec my-service --cluster my-cluster

Specify Container and Command

Specify a particular container and command to run:

ecsctl exec my-service --cluster my-cluster --container web-app --command "python manage.py migrate"