DevDocsDev Docs
ECS

ECS CLI Reference

AWS CLI commands for ECS

Complete reference for AWS ECS CLI commands with examples.

Clusters

Create Cluster

# Simple cluster
aws ecs create-cluster --cluster-name my-cluster

# With Container Insights
aws ecs create-cluster \
  --cluster-name my-cluster \
  --settings name=containerInsights,value=enabled

# With capacity providers
aws ecs create-cluster \
  --cluster-name my-cluster \
  --capacity-providers FARGATE FARGATE_SPOT \
  --default-capacity-provider-strategy \
    capacityProvider=FARGATE,weight=1,base=1 \
    capacityProvider=FARGATE_SPOT,weight=4

# With tags
aws ecs create-cluster \
  --cluster-name my-cluster \
  --tags key=Environment,value=prod

List Clusters

aws ecs list-clusters

Describe Cluster

aws ecs describe-clusters --clusters my-cluster

# With statistics
aws ecs describe-clusters \
  --clusters my-cluster \
  --include STATISTICS SETTINGS CONFIGURATIONS

Update Cluster Settings

aws ecs update-cluster-settings \
  --cluster my-cluster \
  --settings name=containerInsights,value=enabled

Delete Cluster

aws ecs delete-cluster --cluster my-cluster

Task Definitions

Register Task Definition

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

List Task Definitions

# All families
aws ecs list-task-definitions

# Filter by family
aws ecs list-task-definitions --family-prefix my-app

# Only active
aws ecs list-task-definitions --status ACTIVE

Describe Task Definition

aws ecs describe-task-definition --task-definition my-app:1

# Include tags
aws ecs describe-task-definition \
  --task-definition my-app:1 \
  --include TAGS

Deregister Task Definition

aws ecs deregister-task-definition --task-definition my-app:1

Delete Task Definitions

aws ecs delete-task-definitions --task-definitions my-app:1 my-app:2

Services

Create Service

# Fargate service
aws ecs create-service \
  --cluster my-cluster \
  --service-name my-service \
  --task-definition my-app:1 \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration '{
    "awsvpcConfiguration": {
      "subnets": ["subnet-abc123", "subnet-def456"],
      "securityGroups": ["sg-123abc"],
      "assignPublicIp": "ENABLED"
    }
  }'

# With load balancer
aws ecs create-service \
  --cluster my-cluster \
  --service-name my-service \
  --task-definition my-app:1 \
  --desired-count 3 \
  --launch-type FARGATE \
  --network-configuration '{
    "awsvpcConfiguration": {
      "subnets": ["subnet-abc123"],
      "securityGroups": ["sg-123abc"],
      "assignPublicIp": "DISABLED"
    }
  }' \
  --load-balancers '[
    {
      "targetGroupArn": "arn:aws:elasticloadbalancing:...",
      "containerName": "app",
      "containerPort": 3000
    }
  ]' \
  --health-check-grace-period-seconds 60

# With capacity provider strategy
aws ecs create-service \
  --cluster my-cluster \
  --service-name my-service \
  --task-definition my-app:1 \
  --desired-count 4 \
  --capacity-provider-strategy \
    capacityProvider=FARGATE,weight=1,base=1 \
    capacityProvider=FARGATE_SPOT,weight=4

# With deployment configuration
aws ecs create-service \
  --cluster my-cluster \
  --service-name my-service \
  --task-definition my-app:1 \
  --desired-count 2 \
  --launch-type FARGATE \
  --deployment-configuration '{
    "deploymentCircuitBreaker": {
      "enable": true,
      "rollback": true
    },
    "maximumPercent": 200,
    "minimumHealthyPercent": 100
  }'

# With service discovery
aws ecs create-service \
  --cluster my-cluster \
  --service-name my-service \
  --task-definition my-app:1 \
  --service-registries registryArn=arn:aws:servicediscovery:...

List Services

aws ecs list-services --cluster my-cluster

Describe Services

aws ecs describe-services \
  --cluster my-cluster \
  --services my-service

# Multiple services
aws ecs describe-services \
  --cluster my-cluster \
  --services my-service-1 my-service-2

Update Service

# Update task definition
aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --task-definition my-app:2

# Scale up/down
aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --desired-count 5

# Force new deployment
aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --force-new-deployment

# Update capacity provider strategy
aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --capacity-provider-strategy \
    capacityProvider=FARGATE_SPOT,weight=1

Delete Service

# Scale to 0 first
aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --desired-count 0

# Delete
aws ecs delete-service \
  --cluster my-cluster \
  --service my-service

# Force delete (stops tasks)
aws ecs delete-service \
  --cluster my-cluster \
  --service my-service \
  --force

Tasks

Run Task

# Run standalone task
aws ecs run-task \
  --cluster my-cluster \
  --task-definition my-app:1 \
  --launch-type FARGATE \
  --network-configuration '{
    "awsvpcConfiguration": {
      "subnets": ["subnet-abc123"],
      "securityGroups": ["sg-123abc"],
      "assignPublicIp": "ENABLED"
    }
  }'

# Run multiple instances
aws ecs run-task \
  --cluster my-cluster \
  --task-definition my-app:1 \
  --count 3

# With overrides
aws ecs run-task \
  --cluster my-cluster \
  --task-definition my-app:1 \
  --overrides '{
    "containerOverrides": [
      {
        "name": "app",
        "command": ["./migrate.sh"],
        "environment": [
          {"name": "RUN_MIGRATIONS", "value": "true"}
        ]
      }
    ]
  }'

List Tasks

# All tasks in cluster
aws ecs list-tasks --cluster my-cluster

# Filter by service
aws ecs list-tasks \
  --cluster my-cluster \
  --service-name my-service

# Filter by status
aws ecs list-tasks \
  --cluster my-cluster \
  --desired-status RUNNING

Describe Tasks

aws ecs describe-tasks \
  --cluster my-cluster \
  --tasks task-id-1 task-id-2

Stop Task

aws ecs stop-task \
  --cluster my-cluster \
  --task task-id \
  --reason "Manual stop"

Execute Command (ECS Exec)

# Enable execute command on service
aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --enable-execute-command

# Run command
aws ecs execute-command \
  --cluster my-cluster \
  --task task-id \
  --container app \
  --interactive \
  --command "/bin/sh"

Container Instances (EC2 Launch Type)

List Container Instances

aws ecs list-container-instances --cluster my-cluster

Describe Container Instances

aws ecs describe-container-instances \
  --cluster my-cluster \
  --container-instances instance-id-1 instance-id-2

Drain Container Instance

aws ecs update-container-instances-state \
  --cluster my-cluster \
  --container-instances instance-id \
  --status DRAINING

Deregister Container Instance

aws ecs deregister-container-instance \
  --cluster my-cluster \
  --container-instance instance-id \
  --force

Capacity Providers

Create Capacity Provider

aws ecs create-capacity-provider \
  --name my-cp \
  --auto-scaling-group-provider '{
    "autoScalingGroupArn": "arn:aws:autoscaling:...",
    "managedScaling": {
      "status": "ENABLED",
      "targetCapacity": 80,
      "minimumScalingStepSize": 1,
      "maximumScalingStepSize": 10
    },
    "managedTerminationProtection": "ENABLED"
  }'

Update Cluster Capacity Providers

aws ecs put-cluster-capacity-providers \
  --cluster my-cluster \
  --capacity-providers FARGATE FARGATE_SPOT my-cp \
  --default-capacity-provider-strategy \
    capacityProvider=my-cp,weight=1,base=1

Auto Scaling

Register Scalable Target

aws application-autoscaling register-scalable-target \
  --service-namespace ecs \
  --resource-id service/my-cluster/my-service \
  --scalable-dimension ecs:service:DesiredCount \
  --min-capacity 2 \
  --max-capacity 20

Put Scaling Policy

# Target tracking - CPU
aws application-autoscaling put-scaling-policy \
  --service-namespace ecs \
  --resource-id service/my-cluster/my-service \
  --scalable-dimension ecs:service:DesiredCount \
  --policy-name cpu-scaling \
  --policy-type TargetTrackingScaling \
  --target-tracking-scaling-policy-configuration '{
    "TargetValue": 70.0,
    "PredefinedMetricSpecification": {
      "PredefinedMetricType": "ECSServiceAverageCPUUtilization"
    },
    "ScaleOutCooldown": 60,
    "ScaleInCooldown": 120
  }'

# Target tracking - Memory
aws application-autoscaling put-scaling-policy \
  --service-namespace ecs \
  --resource-id service/my-cluster/my-service \
  --scalable-dimension ecs:service:DesiredCount \
  --policy-name memory-scaling \
  --policy-type TargetTrackingScaling \
  --target-tracking-scaling-policy-configuration '{
    "TargetValue": 70.0,
    "PredefinedMetricSpecification": {
      "PredefinedMetricType": "ECSServiceAverageMemoryUtilization"
    }
  }'

# Target tracking - ALB requests
aws application-autoscaling put-scaling-policy \
  --service-namespace ecs \
  --resource-id service/my-cluster/my-service \
  --scalable-dimension ecs:service:DesiredCount \
  --policy-name request-scaling \
  --policy-type TargetTrackingScaling \
  --target-tracking-scaling-policy-configuration '{
    "TargetValue": 1000.0,
    "PredefinedMetricSpecification": {
      "PredefinedMetricType": "ALBRequestCountPerTarget",
      "ResourceLabel": "app/my-alb/1234/targetgroup/my-tg/5678"
    }
  }'

Describe Scaling Policies

aws application-autoscaling describe-scaling-policies \
  --service-namespace ecs \
  --resource-id service/my-cluster/my-service

Tags

# Tag cluster
aws ecs tag-resource \
  --resource-arn arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster \
  --tags key=Environment,value=prod

# Tag service
aws ecs tag-resource \
  --resource-arn arn:aws:ecs:us-east-1:123456789012:service/my-cluster/my-service \
  --tags key=Team,value=backend

# List tags
aws ecs list-tags-for-resource \
  --resource-arn arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster

# Untag
aws ecs untag-resource \
  --resource-arn arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster \
  --tag-keys Environment

Common Workflows

Deploy New Version

# Register new task definition
NEW_TASK=$(aws ecs register-task-definition \
  --cli-input-json file://task-definition.json \
  --query 'taskDefinition.taskDefinitionArn' \
  --output text)

# Update service
aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --task-definition $NEW_TASK

# Wait for deployment
aws ecs wait services-stable \
  --cluster my-cluster \
  --services my-service

Get Task Logs

# Get task ID
TASK_ID=$(aws ecs list-tasks \
  --cluster my-cluster \
  --service-name my-service \
  --query 'taskArns[0]' \
  --output text | cut -d'/' -f3)

# Get logs
aws logs get-log-events \
  --log-group-name /ecs/my-app \
  --log-stream-name "ecs/app/$TASK_ID"

Force Restart All Tasks

aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --force-new-deployment

AWS ECS

Run and manage Docker containers at scale

AWS ECR

Fully managed Docker container registry

On this page

Clusters
Create Cluster
List Clusters
Describe Cluster
Update Cluster Settings
Delete Cluster
Task Definitions
Register Task Definition
List Task Definitions
Describe Task Definition
Deregister Task Definition
Delete Task Definitions
Services
Create Service
List Services
Describe Services
Update Service
Delete Service
Tasks
Run Task
List Tasks
Describe Tasks
Stop Task
Execute Command (ECS Exec)
Container Instances (EC2 Launch Type)
List Container Instances
Describe Container Instances
Drain Container Instance
Deregister Container Instance
Capacity Providers
Create Capacity Provider
Update Cluster Capacity Providers
Auto Scaling
Register Scalable Target
Put Scaling Policy
Describe Scaling Policies
Tags
Common Workflows
Deploy New Version
Get Task Logs
Force Restart All Tasks