ECS Operations Review Skill

Overview

Execute a comprehensive Amazon ECS operations review across the 6 review pillars with ✓/✗/N/A observations, 7-day CloudWatch baseline metrics, and alarm threshold recommendations for IDR onboarding.

Usage

• User mentions "ECS operations review", "ECS assessment", "ECS review"
• User provides ECS service ARN(s) for operations review
• User asks to review ECS services for a workload
• User requests ECS reliability or security review
• Delegated ECS service assessment from UOPS

Core Concepts

• Review Pillars: Six assessment dimensions — Resiliency & HA, Observability, Security, Operations, Performance, Additional Analysis
• ECS Service/Cluster: The primary resources assessed — includes tasks, services, and cluster configuration
• AWS API: Public AWS service APIs used for all data collection, called read-only (describe/list/get) via the AWS CLI, an AWS SDK, or an AWS API MCP
• Baseline Metrics: 7-day CloudWatch metric history used to establish normal operating patterns

Prerequisites

• Read-only AWS API access (describe/list/get) for ECS, CloudWatch, IAM, Application Auto Scaling, ELB, ECR, EC2 APIs — via AWS CLI, an AWS SDK, or an AWS API MCP
• AWS Knowledge MCP access (search_documentation, read_documentation, recommend, list_regions, get_regional_availability)
• AWS account ID and region
• CloudWatch metrics access (7-day minimum for baseline)
• ECS service ARN — format: arn:aws*:ecs:::service//

Skill Files

• references/checks.md — Checks index: pillar→file map, check-ID ranges, counts, and the access-limitation / minimum-baseline rules. Read this FIRST.
• references/pillars/resiliency.md — Resiliency & HA checks (REL1-REL14). Read only when running the Resiliency pillar.
• references/pillars/observability.md — Observability checks (OBS1-OBS9). Read only when running the Observability pillar.
• references/pillars/security.md — Security checks (SEC1-SEC20). Read only when running the Security pillar.
• references/pillars/operations.md — Operations checks (OPS1-OPS9). Read only when running the Operations pillar.
• references/pillars/performance.md — Performance checks (PERF1-PERF11). Read only when running the Performance pillar.
• references/pillars/additional-analysis.md — Additional Analysis checks (ADD1-ADD7). Read only when running the Additional pillar.
• references/alarm-thresholds.md — Recommended CloudWatch alarm thresholds for IDR onboarding.
• references/common-checks-coverage.md — Crosswalk proving the review covers the shared review-common baseline (tagging, encryption, IAM least-privilege, alarms, logging, cost) via existing ECS check IDs. Read for any full review / CWR.
• references/report-format.md — Required report/artifact structure, severity model, finding-block format, and the coverage gate. Read before generating the report.

Context Management for Checks

Do NOT read all 6 pillar files at once. Read references/checks.md (the index) first, then read each references/pillars/<pillar>.md file ONE AT A TIME as you run that pillar's checks. Agent may add checks beyond the baseline using the next sequential ID in the pillar.

Assessment Workflow

This skill is self-contained — the procedural workflow is embedded below (this copy lives in aws-operations-review and does not depend on any external agent-sops/ SOP). Execute the steps in order; this skill's references/ files supply the check definitions and alarm thresholds.

1. Setup — Create the output directory and a scratchpad for raw API responses. Record account ID, region, and timestamp.
2. Parse ARN — Validate the ECS service ARN (arn:aws*:ecs:*:*:service/*/*); extract cluster name and service name. Halt if the ARN region does not match the region parameter.
3. Collect configuration data — Call the AWS APIs following the tier order in the API Tier Dependency Chain below. Tier 1 (ecs.describeServices) MUST succeed before any other call. Save each response verbatim to the scratchpad. On non-Tier-1 access/API errors, mark dependent checks N/A and continue.
4. Resolve compute platform — Before grading any pillar, classify the service's compute platform from launchType + capacityProviderStrategy + ecs.describeCapacityProviders: Fargate (FARGATE/FARGATE_SPOT), EC2 ASG capacity provider (autoScalingGroupProvider), Managed Instances (managedInstancesProvider), launchType-only EC2/Fargate (no strategy), or ECS Anywhere (EXTERNAL). Mixed strategies are valid — record every platform present. This decision drives check applicability in every pillar (full rules in references/checks.md). Record the platform in the report header.
5. Run pillar checks — Read references/checks.md (the index) first, then for EACH pillar read its references/pillars/<pillar>.md file one at a time and apply its checks against the collected data, recording ✓ / ✗ / N/A with an observation. Use the exact check IDs and severities; mark platform-specific checks N/A where they don't apply (per the resolved compute platform). May add checks beyond the baseline.
6. Generate report — Produce the per-service review artifact following references/report-format.md exactly (Workload Details, per-pillar ✓/✗/N/A scorecards for all 6 pillars, Prioritized Action Plan, Detailed Findings, Recommended CloudWatch Alarms from references/alarm-thresholds.md, Access Limitations, Review Summary). Before finalizing, run the report-format Coverage gate — every check ID across all 6 pillars must appear in a scorecard as ✓/✗/N/A (including passes; no pillar dropped or truncated), the alarms table must be present, every ✗ needs a detailed finding block, and the shared review-common baseline must be accounted for per references/common-checks-coverage.md (all eight common checks covered via their ECS equivalents or ⚪ N/A with a reason). Default to a Markdown artifact; render DOCX only if asked (build from the same content). Strip internal check IDs from the customer-facing report. Return the Review Summary with verified counts, then delete the scratchpad.

Review Pillars:

• Resiliency and High Availability (REL1-REL14) — Multi-AZ, desired count, deployment config, circuit breaker, deployment alarms, health checks, subnet AZ spread, capacity-provider managed termination protection, target-group deregistration delay, capacity provider infrastructure multi-AZ
• Observability (OBS1-OBS9) — Container Insights, CloudWatch alarms, logging, log retention, distributed tracing, metrics monitoring
• Security (SEC1-SEC20) — IAM least privilege, network mode, secrets management, ECR image scanning, security groups, VPC endpoints, private connectivity, encryption at rest, encryption in transit (TLS), VPC Flow Logs, GuardDuty Runtime Monitoring
• Operations (OPS1-OPS9) — Deployment controller, resource tagging, IaC-managed, platform version, ECS agent version, ECS Exec posture and session audit logging
• Performance (PERF1-PERF11) — Auto scaling, CPU/memory rightsizing, capacity provider strategy, managed scaling / targetCapacity headroom, CapacityProviderReservation 7-day baseline analysis, base/weight strategy design, Compute Optimizer recommendations
• Additional Analysis & Recommendations (ADD1-ADD7) — Graviton/ARM64, Fargate Spot, Service Connect, cost optimization, CloudWatch Logs Insights queries, ECS Managed Instances evaluation

AWS API Summary

All calls below are public AWS API operations. Use read-only (describe/list/get) operations only, via the AWS CLI, an AWS SDK (e.g. boto3), or an AWS API MCP with least-privilege read-only credentials.

ECS APIs (Tier 1, 2, 3)

API	Tier	Purpose
ecs.describeServices	1	Foundation — service config, task def, LB, deployment, network
ecs.describeTaskDefinition	2	Container defs, CPU/memory, roles, log config, network mode
ecs.describeClusters	2	Cluster settings, Container Insights, capacity providers, Exec logging config (include=["CONFIGURATIONS"] for OPS9)
ecs.listTasks	2	Running task ARNs for the service
ecs.describeTasks	3	Task health, AZ spread, connectivity status
ecs.listContainerInstances	2	Container instance ARNs for EC2 launch type clusters
ecs.describeContainerInstances	3	Agent version, AMI ID, instance status (EC2 only)
ecs.describeCapacityProviders	2	Compute platform classification (ASG vs Managed Instances vs Fargate), managed termination protection (REL12), managed scaling status/targetCapacity (PERF9), MI network config (REL14)

Application Auto Scaling APIs (Tier 2)

API	Tier	Purpose
applicationautoscaling.describeScalingPolicies	2	Auto scaling policies for the service
applicationautoscaling.describeScalableTargets	2	Min/max capacity configuration

ELB APIs (Tier 2)

API	Tier	Purpose
alb.describeTargetHealth	2	Target health for service tasks behind ALB/NLB (skip if no LB configured)
alb.describeTargetGroups	2	Target group details including LoadBalancerArns — used to determine LB type (ALB vs NLB) by ARN path segment: /app/ = ALB, /net/ = NLB, for correct alarm recommendations (skip if no LB configured)
elbv2.describeListeners	2	Listener protocol/port for the LB fronting the service — HTTPS/TLS vs plaintext HTTP/TCP for encryption-in-transit (SEC20); uses LoadBalancerArns from describeTargetGroups (skip if no LB configured)

IAM APIs (Tier 4a, 4b)

API	Tier	Purpose
iam.listAttachedRolePolicies	4a	Managed policies on execution/task roles
iam.listRolePolicies	4a	Inline policy names on execution/task roles
iam.getRolePolicy	4b	Inline policy document for execution/task roles

ECR APIs (Tier 3)

API	Tier	Purpose
ecr.describeRepositories	3	Image scanning config, tag immutability for container image repos

EC2/VPC APIs (Tier 2, 3, 4)

API	Tier	Purpose
ec2.describeSecurityGroups	2	Security group rules for service ENIs (awsvpc mode)
ec2.describeSubnets	2	Subnet AZ distribution for service network config
ec2.describeVpcEndpoints	3	VPC endpoints for ECR, CloudWatch Logs, Secrets Manager (uses VPC ID from describeSubnets)
ec2.describeRouteTables	3	Route table entries for NAT/internet access assessment
ec2.describeNatGateways	3	NAT Gateway availability for private subnets
ec2.describeImages	4	AMI creation date for container instance AMI currency check (EC2 only, uses imageId from describeContainerInstances)
ec2.describeVolumes	3	EBS volume encryption status for task-attached / container-instance volumes (SEC17)
ec2.describeFlowLogs	3	VPC Flow Logs enablement for the service VPC (SEC18, uses VPC ID from describeSubnets)

CloudWatch APIs (Tier 2, 5)

API	Tier	Purpose
cloudwatch.describeAlarms	2	Existing alarms for ECS service
cloudwatch.getMetricStatistics	5	7-day baseline: CPU, memory, task count; plus CapacityProviderReservation (AWS/ECS/ManagedScaling) for EC2 ASG capacity providers (PERF10)

CloudWatch Logs APIs (Tier 3)

API	Tier	Purpose
logs.describeLogGroups	3	Log retention setting and Logs Insights query targeting for the awslogs group (OBS8, ADD6 — uses awslogs-group from task definition)

GuardDuty APIs (Tier 2)

API	Tier	Purpose
guardduty.listDetectors	2	Detector presence in region (SEC19)
guardduty.getDetector	2	Runtime Monitoring feature status for ECS (SEC19 — uses detector ID from listDetectors)

Compute Optimizer APIs (Tier 2)

API	Tier	Purpose
computeoptimizer.getECSServiceRecommendations	2	ECS service task CPU/memory rightsizing recommendations (PERF8)

AWS Knowledge MCP

Tool	Purpose
aws___search_documentation	Search across all AWS documentation with optional topic-based filtering
aws___read_documentation	Retrieve and convert AWS documentation pages to markdown
aws___recommend	Get content recommendations for AWS documentation pages
aws___list_regions	Retrieve a list of all AWS regions
aws___get_regional_availability	Retrieve AWS regional availability information

API Tier Dependency Chain

Tier 1: ecs.describeServices (FOUNDATION — must complete first)
  ├─ extracts: taskDefinition ARN, clusterArn, loadBalancers,
  │            desiredCount, launchType, networkConfiguration, tags
  │
  ├─► Tier 2 (parallel): ecs.describeTaskDefinition, ecs.describeClusters,
  │     ecs.listTasks, cloudwatch.describeAlarms,
  │     applicationautoscaling.describeScalingPolicies,
  │     applicationautoscaling.describeScalableTargets,
  │     ecs.describeCapacityProviders (compute platform classification;
  │       ASG providers — REL12/PERF9; Managed Instances providers — REL14),
  │     guardduty.listDetectors ─► guardduty.getDetector (SEC19),
  │     computeoptimizer.getECSServiceRecommendations (PERF8),
  │     alb.describeTargetHealth (if LB configured),
  │     alb.describeTargetGroups (if LB configured — resolves ALB vs NLB type from LoadBalancerArns: /app/ = ALB, /net/ = NLB; also deregistration delay for REL13),
  │     elbv2.describeListeners (if LB configured — listener protocol for encryption-in-transit SEC20),
  │     ec2.describeSecurityGroups (from networkConfiguration.securityGroups),
  │     ec2.describeSubnets (from networkConfiguration.subnets),
  │     ecs.listContainerInstances (EC2 launch type only)
  │     │
  │     ├─► Tier 3: ecs.describeTasks (using task ARNs from listTasks)
  │     │            ecs.describeContainerInstances (EC2 only, using instance ARNs from listContainerInstances)
  │     │            ecr.describeRepositories (using repo name from task definition image URI)
  │     │            ec2.describeVpcEndpoints (using VPC ID from describeSubnets)
  │     │            ec2.describeRouteTables (using subnet IDs from describeSubnets)
  │     │            ec2.describeNatGateways (using VPC ID from describeSubnets)
  │     │            ec2.describeFlowLogs (using VPC ID from describeSubnets — SEC18)
  │     │            ec2.describeVolumes (task-attached / container-instance EBS encryption — SEC17)
  │     │            logs.describeLogGroups (using awslogs-group from task definition — OBS8, ADD6)
  │     │
  │     ├─► Tier 4 (EC2 only): ec2.describeImages (using imageId from describeContainerInstances)
  │     │
  │     └─► Tier 4a (parallel): iam.listAttachedRolePolicies (execution + task role),
  │           iam.listRolePolicies (execution + task role)
  │           │
  │           └─► Tier 4b: iam.getRolePolicy (execution + task role)
  │                 (uses policy names from listRolePolicies)
  │
  └─► Tier 5 (per-metric loop): cloudwatch.getMetricStatistics

Access Limitation Handling

When AWS API calls return access denied or authorization errors:

• Mark dependent checks as N/A with observation: "Unable to assess — access denied on {{api_name}}. Manual verification recommended."
• Include a dedicated Access Limitations section in the report listing all checks that could not be evaluated due to permissions
• Continue with remaining assessable checks — do NOT halt the entire assessment for non-Tier-1 access errors
• In the Review Summary, note how many checks could not be evaluated due to access limitations

Example Output

The agent produces a per-service review artifact (Markdown by default; DOCX if asked) containing: service configuration summary, all 6 review pillar scorecards (✓/✗/N/A with observations, every check including passes), 7-day baseline metrics, the recommended-alarms table with clickable doc links, and priority action items. A Review Summary with verified counts is returned to the orchestrator.

What Not to Do

• Don't skip any pillar — all 6 must be assessed
• Don't use write or mutating API calls — this is a read-only assessment; use describe/list/get operations only
• Don't hardcode doc URLs for ✗ check findings — use AWS Knowledge MCP (aws___search_documentation) to supplement the doc links provided in checks.md
• Don't hardcode doc URLs for alarm recommendation hyperlinks — use the doc_url column from references/alarm-thresholds.md as the canonical link target
• Don't skip alarm recommendations — this is a core IDR deliverable
• Don't omit the metrics baseline section — if 7-day data is unavailable, note the limitation in the report rather than skipping it
• Don't hallucinate findings — only report what AWS API data confirms
• Don't silently skip checks when access is denied — always mark as N/A with explicit access limitation note

Failure Recovery

• If ecs.describeServices fails after retries: HALT workflow — delete {{scratchpad_dir}}/ and return error to orchestrator
• If Tier 2-5 APIs fail: mark dependent checks as N/A, continue assessment with available data
• If report generation fails: default to the Markdown artifact (no external dependency); only fall back to DOCX (python-docx, retry with --user on install failure) when a DOCX deliverable was explicitly requested
• If artifact write fails: capture the error, delete scratchpad, return error to orchestrator

Success Criteria

• All 6 review pillars assessed with ✓/✗/N/A observations — coverage gate passed: every check ID across all 6 pillars appears in a scorecard (including passes), no pillar dropped or truncated
• Review artifact generated at {{output_directory}}/ (Markdown by default; DOCX only if requested)
• Recommended-alarms table populated from alarm-thresholds.md, marking exist-vs-missing
• 7-day baseline metrics included (or limitation noted)
• Every ✗ has a detailed finding block; every recommendation includes a resolvable AWS documentation link
• Access limitations explicitly documented; unobtainable checks are N/A-with-reason, never omitted or guessed
• Review Summary with verified counts returned to orchestrator
• {{scratchpad_dir}}/ deleted after report verified