cloudthinker-ai AWS ECS Skill
Analyze AWS ECS clusters, services, and tasks with parallel execution and anti-hallucination guardrails.
Relationship to other AWS skills:
aws-ecs/→ ECS-specific analysis (clusters, services, tasks, capacity providers)aws/→ "How to execute" (parallel patterns, throttling, output format)
CRITICAL: Parallel Execution Requirement
ALL independent operations MUST run in parallel using background jobs (&) and wait.
#!/bin/bash
export AWS_PAGER=""
# CORRECT: Parallel service analysis
for service in $services; do
describe_service "$cluster" "$service" &
done
wait
FORBIDDEN: Sequential loops for independent describe calls.
Helper Functions
#!/bin/bash
export AWS_PAGER=""
# List all clusters
list_clusters() {
aws ecs list-clusters --output text --query 'clusterArns[]' | tr '\t' '\n' | sed 's|.*/||'
}
# Get cluster details
describe_cluster() {
local cluster=$1
aws ecs describe-clusters --clusters "$cluster" \
--include STATISTICS ATTACHMENTS \
--output text \
--query 'clusters[].[clusterName,status,registeredContainerInstancesCount,runningTasksCount,pendingTasksCount,activeServicesCount]'
}
# List services in a cluster
list_services() {
local cluster=$1
aws ecs list-services --cluster "$cluster" \
--output text --query 'serviceArns[]' | tr '\t' '\n' | sed 's|.*/||'
}
# Get service details
describe_service() {
local cluster=$1 service=$2
aws ecs describe-services --cluster "$cluster" --services "$service" \
--output text \
--query 'services[].[serviceName,status,desiredCount,runningCount,pendingCount,launchType,deployments[0].rolloutState]'
}
# Get recent task failures
get_stopped_tasks() {
local cluster=$1
aws ecs list-tasks --cluster "$cluster" --desired-status STOPPED \
--output text --query 'taskArns[]' | tr '\t' '\n' | head -10
}
# Describe tasks (batch)
describe_tasks() {
local cluster=$1
shift
local task_arns="$@"
[ -z "$task_arns" ] && return
aws ecs describe-tasks --cluster "$cluster" --tasks $task_arns \
--output text \
--query 'tasks[].[taskArn,lastStatus,stoppedReason,stopCode,containers[0].exitCode]'
}
# Get service events (last 5)
get_service_events() {
local cluster=$1 service=$2
aws ecs describe-services --cluster "$cluster" --services "$service" \
--output text \
--query 'services[0].events[:5].[createdAt,message]'
}
Common Operations
1. Cluster Health Overview
#!/bin/bash
export AWS_PAGER=""
CLUSTERS=$(aws ecs list-clusters --output text --query 'clusterArns[]' | tr '\t' '\n' | sed 's|.*/||')
for cluster in $CLUSTERS; do
aws ecs describe-clusters --clusters "$cluster" \
--include STATISTICS \
--output text \
--query 'clusters[].[clusterName,status,registeredContainerInstancesCount,runningTasksCount,pendingTasksCount,activeServicesCount]' &
done
wait
2. Service Deployment Status
#!/bin/bash
export AWS_PAGER=""
CLUSTER=$1
SERVICES=$(aws ecs list-services --cluster "$CLUSTER" --output text --query 'serviceArns[]' | tr '\t' '\n' | sed 's|.*/||')
for svc in $SERVICES; do
aws ecs describe-services --cluster "$CLUSTER" --services "$svc" \
--output text \
--query 'services[].[serviceName,desiredCount,runningCount,deployments[0].rolloutState,deployments[0].taskDefinition]' &
done
wait
3. Task Failure Investigation
#!/bin/bash
export AWS_PAGER=""
CLUSTER=$1
TASK_ARNS=$(aws ecs list-tasks --cluster "$CLUSTER" --desired-status STOPPED \
--output text --query 'taskArns[]' | tr '\t' '\n' | head -20)
[ -z "$TASK_ARNS" ] && echo "No stopped tasks" && exit 0
aws ecs describe-tasks --cluster "$CLUSTER" --tasks $TASK_ARNS \
--output text \
--query 'tasks[].[group,lastStatus,stoppedReason,stopCode,containers[0].exitCode,stoppedAt]'
4. Capacity Provider Analysis
#!/bin/bash
export AWS_PAGER=""
CLUSTERS=$(aws ecs list-clusters --output text --query 'clusterArns[]' | tr '\t' '\n' | sed 's|.*/||')
for cluster in $CLUSTERS; do
aws ecs describe-clusters --clusters "$cluster" \
--include ATTACHMENTS \
--output text \
--query 'clusters[].[clusterName,capacityProviders[],defaultCapacityProviderStrategy[].[capacityProvider,weight,base]]' &
done
wait
5. Container Resource Utilization
#!/bin/bash
export AWS_PAGER=""
CLUSTER=$1
END=$(date -u +"%Y-%m-%dT%H:%M:%S")
START=$(date -u -d "1 day ago" +"%Y-%m-%dT%H:%M:%S" 2>/dev/null || date -u -v-1d +"%Y-%m-%dT%H:%M:%S")
SERVICES=$(aws ecs list-services --cluster "$CLUSTER" --output text --query 'serviceArns[]' | tr '\t' '\n' | sed 's|.*/||')
for svc in $SERVICES; do
{
cpu=$(aws cloudwatch get-metric-statistics \
--namespace AWS/ECS --metric-name CPUUtilization \
--dimensions Name=ClusterName,Value="$CLUSTER" Name=ServiceName,Value="$svc" \
--start-time "$START" --end-time "$END" \
--period 86400 --statistics Average Maximum \
--output text --query 'Datapoints[0].[Average,Maximum]')
mem=$(aws cloudwatch get-metric-statistics \
--namespace AWS/ECS --metric-name MemoryUtilization \
--dimensions Name=ClusterName,Value="$CLUSTER" Name=ServiceName,Value="$svc" \
--start-time "$START" --end-time "$END" \
--period 86400 --statistics Average Maximum \
--output text --query 'Datapoints[0].[Average,Maximum]')
printf "%s\tCPU:%s\tMEM:%s\n" "$svc" "$cpu" "$mem"
} &
done
wait
Anti-Hallucination Rules
- Never assume launch type - Always check
launchTypefield. Services can be FARGATE, EC2, or EXTERNAL. Do not assume Fargate. - Desired vs Running count -
desiredCount != runningCountdoes not always mean failure. It can indicate scaling in progress. - Task definition != running version - Services may have multiple deployments active during rolling updates. Check
deployments[]not justtaskDefinition. - Container Insights required - CPU/Memory utilization metrics require Container Insights enabled on the cluster. If no metrics exist, check cluster settings.
- Service ARN format changed - Newer accounts use long ARN format. Always parse service name from the end of the ARN.
Output Format
Present results as a structured report:
Aws Ecs Report
══════════════
Resources discovered: [count]
Resource Status Key Metric Issues
──────────────────────────────────────────────
[name] [ok/warn] [value] [findings]
Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]
Target ≤50 lines of output. Use tables for multi-resource comparisons.
Counter-Rationalizations
| Shortcut | Counter | Why |
|---|---|---|
| "I'll skip discovery and check known resources" | Always run Phase 1 discovery first | Resource names change, new resources appear — assumed names cause errors |
| "The user only asked for a quick check" | Follow the full discovery → analysis flow | Quick checks miss critical issues; structured analysis catches silent failures |
| "Default configuration is probably fine" | Audit configuration explicitly | Defaults often leave logging, security, and optimization features disabled |
| "Metrics aren't needed for this" | Always check relevant metrics when available | API/CLI responses show current state; metrics reveal trends and intermittent issues |
| "I don't have access to that" | Try the command and report the actual error | Assumed permission failures prevent useful investigation; actual errors are informative |
Common Pitfalls
- Batch describe limits:
describe-tasksaccepts max 100 task ARNs per call. Chunk if needed. - Service vs task metrics: CloudWatch ECS metrics are at service level (ClusterName + ServiceName dimensions), not individual task level.
- Stopped task retention: ECS only retains stopped tasks for ~1 hour. For historical failures, use CloudWatch Logs or EventBridge.
- Fargate platform version: Check
platformVersionfor Fargate tasks.LATESTis not always the newest version. - CloudWatch statistics syntax: Use spaces not commas:
--statistics Average Maximum(NOTAverage,Maximum).