AWS ECS CLI Commands for Container Management

This cheatsheet provides essential AWS Command Line Interface (CLI) commands for managing Amazon Elastic Container Service (ECS) resources. Efficiently handle your containerized applications with these practical examples.

Register Task Definitions

Register a new task definition for your ECS services. This defines the Docker image, CPU, memory, environment variables, and other parameters for your tasks.

$ aws --profile default ecs register-task-definition --cli-input-json file://taskdef.json

Describe Task Definitions

Retrieve detailed information about a specific task definition. This is useful for debugging or understanding the configuration of your running tasks. You can also inspect specific container environments within a task definition.

aws --profile default ecs describe-task-definition --task-definition my-web-service | jq -r '.taskDefinition.containerDefinitions[] | select(.name == "web-container") | .environment'

List ECS Clusters

View all your Amazon ECS clusters associated with a specific AWS profile. This command helps you get an overview of your ECS infrastructure.

$ aws --profile default ecs list-clusters

List ECS Services

Get a list of all services running within a particular ECS cluster. This is crucial for monitoring and managing your deployed applications.

$ aws --profile default ecs list-services --cluster $cluster_name

Describe ECS Service

Obtain detailed status and configuration information for an ECS service. You can check the number of running containers, the task definition revision being used, and other deployment-related details.

$ aws --profile default ecs describe-services --cluster $cluster_name --services $service_name | jq -r '.services[].runningCount'

$ aws --profile default ecs describe-services --cluster $cluster_name --services $service_name | jq -r '.services[].taskDefinition'

Describe ECS Task States

Troubleshoot task failures by examining their states and events. This section covers checking deployment acceptance, retrieving the latest event information, and inspecting task status, stop codes, and reasons.

$ aws --profile default ecs describe-services --cluster $cluster_name --services $service_name | jq -r '.services[].deployments'

$ aws --profile default ecs describe-services --cluster $cluster_name --services $service_name | jq -r '.services[].events[0]'

$ aws --profile default ecs describe-tasks --tasks 00000000-0000-0000-0000-000000000000 --cluster $cluster_name  | jq -r '.tasks[].lastStatus'
STOPPED

$ aws --profile default ecs describe-tasks --tasks 00000000-0000-0000-0000-000000000000 --cluster $cluster_name   | jq -r '.tasks[].stopCode'
TaskFailedToStart

$ aws --profile default ecs describe-tasks --tasks 00000000-0000-0000-0000-000000000000 --cluster $cluster_name   | jq -r '.tasks[].stoppedReason'
Fetching secret data from SSM Parameter Store in eu-west-1: invalid parameters: /demo/dev/MY_INVALID_PARAMETER

Create ECS Service

Create a new ECS service, specifying parameters like the task definition, desired count, scheduling strategy, and capacity providers for flexible resource allocation.

$ aws --profile default ecs create-service --cluster $cluster_name --service-name $service_name --task-definition mytaskdef:1 --desired-count 1 --scheduling-strategy "REPLICA" --capacity-provider-strategy='[{"capacityProvider": "ondemand-capacity","weight": 0, "base": 1},{"capacityProvider": "spot-capacity", "weight": 100, "base": 0}]'

Update ECS Service

Modify an existing ECS service. This includes updating to the latest task definition revision, adjusting the desired number of running tasks, or changing capacity provider strategies. Use `--force-new-deployment` to ensure changes are applied immediately.

$ aws --profile default ecs update-service --cluster $cluster_name --service $service_name --task-definition $task_def

$ aws --profile default ecs update-service --cluster $cluster_name --service $service_name --desired-count 3

$ aws --profile default ecs update-service --cluster $cluster_name --service $service_name --capacity-provider-strategy='[{"capacityProvider": "ondemand-capacity", "weight": 0, "base": 1},{"capacityProvider": "spot-capacity", "weight": 100, "base": 0}]' --force-new-deployment

For more advanced ECS management and best practices, refer to the AWS ECS Developer Guide and explore resources on Stack Overflow for community insights.