Imported from terminalskills/skills (skills/aws-ecs/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill aws-ecs. Copyright stays with the author (Apache-2.0).

AWS ECS

Amazon Elastic Container Service (ECS) is a fully managed container orchestration service. Run Docker containers on Fargate (serverless) or self-managed EC2 instances with deep AWS integration.

Core Concepts

• Cluster — logical grouping of tasks and services
• Task Definition — blueprint for containers (image, CPU, memory, ports, env vars)
• Task — a running instance of a task definition
• Service — maintains desired count of tasks, integrates with ALB
• Fargate — serverless compute for containers, no EC2 management
• ECR — Elastic Container Registry for storing Docker images

Cluster Setup

# Create a Fargate cluster
aws ecs create-cluster --cluster-name app-prod --capacity-providers FARGATE FARGATE_SPOT

Task Definitions

// task-definition.json — web application task
{
  "family": "web-app",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "arn:aws:iam::123456789:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::123456789:role/ecsTaskRole",
  "containerDefinitions": [
    {
      "name": "web",
      "image": "123456789.dkr.ecr.us-east-1.amazonaws.com/web-app:latest",
      "portMappings": [{"containerPort": 8080, "protocol": "tcp"}],
      "environment": [
        {"name": "NODE_ENV", "value": "production"}
      ],
      "secrets": [
        {"name": "DATABASE_URL", "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789:secret:db-url"}
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/web-app",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "web"
        }
      },
      "healthCheck": {
        "command": ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"],
        "interval": 30,
        "timeout": 5,
        "retries": 3
      }
    }
  ]
}

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

Services

# Create a service with ALB and Fargate
aws ecs create-service \
  --cluster app-prod \
  --service-name web-app \
  --task-definition web-app:1 \
  --desired-count 3 \
  --launch-type FARGATE \
  --network-configuration '{
    "awsvpcConfiguration": {
      "subnets": ["subnet-aaa", "subnet-bbb"],
      "securityGroups": ["sg-0123456789abcdef0"],
      "assignPublicIp": "DISABLED"
    }
  }' \
  --load-balancers '[{
    "targetGroupArn": "arn:aws:elasticloadbalancing:us-east-1:123456789:targetgroup/web-tg/abc123",
    "containerName": "web",
    "containerPort": 8080
  }]' \
  --deployment-configuration '{
    "maximumPercent": 200,
    "minimumHealthyPercent": 100,
    "deploymentCircuitBreaker": {"enable": true, "rollback": true}
  }'

# Update service (deploy new image)
aws ecs update-service \
  --cluster app-prod \
  --service web-app \
  --task-definition web-app:2 \
  --force-new-deployment

# Scale service
aws ecs update-service \
  --cluster app-prod \
  --service web-app \
  --desired-count 5

Auto Scaling

# Register scalable target
aws application-autoscaling register-scalable-target \
  --service-namespace ecs \
  --resource-id service/app-prod/web-app \
  --scalable-dimension ecs:service:DesiredCount \
  --min-capacity 2 \
  --max-capacity 20

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

ECR (Container Registry)

# Create repository
aws ecr create-repository --repository-name web-app --image-scanning-configuration scanOnPush=true

# Login, build, push
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com
docker build -t web-app .
docker tag web-app:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/web-app:latest
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/web-app:latest

Running One-Off Tasks

# Run a migration task
aws ecs run-task \
  --cluster app-prod \
  --task-definition db-migrate:1 \
  --launch-type FARGATE \
  --network-configuration '{
    "awsvpcConfiguration": {
      "subnets": ["subnet-aaa"],
      "securityGroups": ["sg-0123456789abcdef0"],
      "assignPublicIp": "DISABLED"
    }
  }' \
  --overrides '{
    "containerOverrides": [{"name": "migrate", "command": ["npm", "run", "migrate"]}]
  }'

Monitoring

# List running tasks
aws ecs list-tasks --cluster app-prod --service-name web-app --desired-status RUNNING

# View task logs
aws logs tail /ecs/web-app --follow --since 1h

Best Practices

• Use Fargate for most workloads to eliminate instance management
• Store secrets in Secrets Manager or Parameter Store, not environment variables
• Enable deployment circuit breaker to auto-rollback failed deployments
• Use awslogs driver for centralized logging in CloudWatch
• Set health checks in both the task definition and target group
• Use Fargate Spot for non-critical background workers (up to 70% savings)
• Pin image tags in production; avoid latest for reproducibility