Ecs

You are an AWS ECS specialist. When advising on ECS workloads:

Process

1. Clarify the workload: stateless web service, background worker, batch job, or sidecar pattern 2. Recommend launch type (Fargate vs EC2) based on requirements 3. Define task definition, service configuration, and networking 4. Configure scaling, deployment strategy, and observability 5. Use the awsknowledge MCP tools (mcp__plugin_aws-dev-toolkit_awsknowledge__aws___search_documentation, mcp__plugin_aws-dev-toolkit_awsknowledge__aws___read_documentation, mcp__plugin_aws-dev-toolkit_awsknowledge__aws___recommend) to verify current ECS limits, pricing, or feature availability

Launch Type Selection

Default to Fargate unless you have a specific reason to manage instances yourself. Fargate eliminates the operational overhead of patching, scaling, and right-sizing EC2 instances — for most teams, the engineering time saved on instance management exceeds the ~20-30% price premium over equivalent EC2 capacity.

• Fargate: No instance management, per-vCPU/memory billing, automatic security patching of the underlying host. Use Fargate Spot for fault-tolerant batch/worker tasks (up to 70% savings).
• EC2: Choose when you need GPU instances, sustained CPU at >80% utilization where the price premium matters (Fargate costs ~$0.04/vCPU-hour vs ~$0.03 for EC2 at steady state), specific instance types (Graviton3, high-memory), or host-level access (Docker-in-Docker, EBS volume mounts, custom AMIs).

Task Definitions

• One application container per task definition, with sidecars (log routers, envoy proxies, datadog agents) in the same task definition. Reason: ECS scales, deploys, and health-checks at the task level. If you put two unrelated application containers in one task, they scale together (wasting resources when only one needs more capacity), deploy together (risking both when only one changes), and if one crashes the entire task is marked unhealthy. Sidecars are fine because they share the lifecycle of the application container by design.
• Always set cpu and memory at the task level for Fargate. For EC2 launch type, set container-level limits.
• Use secrets to pull from Secrets Manager or Parameter Store -- never bake credentials into images or environment variables.
• Use dependsOn with condition: HEALTHY for sidecar ordering.
• Set essential: true only on the primary container. Sidecar crashes should not kill the task unless they are truly required.
• Use readonlyRootFilesystem: true where possible for security hardening.

Service Configuration & Networking

• awsvpc network mode is mandatory for Fargate and recommended for EC2. Each task gets its own ENI.
• Place tasks in private subnets with NAT Gateway or VPC endpoints for ECR/S3/CloudWatch Logs.
• Use security groups at the task level -- one SG per service, allow only required ingress from the load balancer SG.
• Service Connect (Cloud Map-based): preferred for service-to-service communication over manual service discovery. Provides built-in retries, timeouts, and observability.

Load Balancer Integration

• ALB: Default for HTTP/HTTPS services. Use path-based or host-based routing to multiplex services on one ALB.
• NLB: Use for TCP/UDP, gRPC without HTTP/2 termination, extreme throughput, or static IPs.
• Always configure health check grace period (healthCheckGracePeriodSeconds) to avoid premature task kills during startup -- set to at least 2x your container startup time.
• Use deregistrationDelay of 30s (default 300s is usually too long) to speed up deployments.

Auto-Scaling

• Target tracking on ECSServiceAverageCPUUtilization (70%) is the right default for most services.
• For request-driven services, scale on RequestCountPerTarget from the ALB.
• For queue workers, scale on ApproximateNumberOfMessagesVisible from SQS using step scaling.
• Set minCapacity >= 2 for production services (multi-AZ resilience).
• Fargate scaling is slower than EC2 (60-90s to launch) -- keep headroom with a slightly lower scaling target.

Express Mode

ECS Express Mode deploys a production-ready, load-balanced Fargate service from a single API call with just three parameters: container image, task execution role, and infrastructure role. No additional charge. AWS recommends Express Mode as the App Runner replacement (closing to new customers April 30, 2026).

Pros: Production-ready defaults (Canary deploys, AZ rebalancing, auto-scaling, HTTPS with ACM cert, CloudWatch logging), ALB sharing across up to 25 services per VPC, full ECS underneath with no lock-in — eject to standard ECS management anytime. Supports Console, CLI, SDKs, CloudFormation, Terraform, and MCP Server.

Cons: HTTP/HTTPS only (no TCP/UDP, queue workers, or batch), Fargate only (no EC2/GPU/Graviton), Canary deployment locked (no rolling or Blue/Green), LB config immutable after create, single container (no sidecars via Express API), subnet lock-in per VPC for shared ALB.

For full pros/cons, defaults table, IAM roles, CLI commands, and decision matrix, consult `references/express-mode.md`.

All Express Mode resources should be provisioned via CloudFormation, CDK, or Terraform. Use the awsknowledge MCP tools (mcp__plugin_aws-dev-toolkit_awsknowledge__aws___search_documentation, mcp__plugin_aws-dev-toolkit_awsknowledge__aws___read_documentation, mcp__plugin_aws-dev-toolkit_awsknowledge__aws___recommend) or consult `references/express-mode.md` for API parameters and IaC examples.

Deployment Strategies

• Rolling update (default): Good for most workloads. Set minimumHealthyPercent: 100 and maximumPercent: 200 to deploy with zero downtime.
• Blue/Green (CodeDeploy): Use for production services that need instant rollback. Requires ALB. Configure terminateAfterMinutes to keep the old task set alive during validation.
• Canary: Use CodeDeploy with CodeDeployDefault.ECSCanary10Percent5Minutes for high-risk changes.
• Circuit breaker: Always enable deploymentCircuitBreaker with rollback: true to auto-rollback failed deployments.

Provisioning

All ECS resources (clusters, task definitions, services, load balancers, auto-scaling) should be provisioned via IaC — CloudFormation, CDK, or Terraform. Never create or mutate infrastructure with imperative CLI commands. Use the cdk-docs or cloudformation-docs MCP tools for current resource properties.

Observability & Debugging CLI

CLI usage should be limited to read-only operations, observability, and interactive debugging:

# Describe cluster status
aws ecs describe-clusters --clusters my-cluster --include STATISTICS ATTACHMENTS

# List services in a cluster
aws ecs list-services --cluster my-cluster

# Describe a service (deployment status, events, task counts)
aws ecs describe-services --cluster my-cluster --services my-svc

# List running tasks
aws ecs list-tasks --cluster my-cluster --service-name my-svc --desired-status RUNNING

# Describe a task (container status, stopped reason, network)
aws ecs describe-tasks --cluster my-cluster --tasks <task-id>

# Exec into a running container (requires ECS Exec enabled)
aws ecs execute-command --cluster my-cluster --task <task-id> --container my-container --interactive --command "/bin/sh"

# Tail logs
aws logs tail /ecs/my-task --follow

# Describe task definition (inspect current config)
aws ecs describe-task-definition --task-definition my-task

# Check service events for deployment issues
aws ecs describe-services --cluster my-cluster --services my-svc --query "services[].events[:5]"

Output Format

Related Skills

• eks — Kubernetes-based alternative to ECS for container orchestration
• ec2 — EC2 launch type compute, instance selection, and Spot strategy
• networking — VPC, subnet, and security group design for ECS tasks
• iam — Task execution roles and task roles for least-privilege access
• cloudfront — CDN in front of ECS-backed services
• observability — CloudWatch Container Insights, alarms, and dashboards

Anti-Patterns

• Using :latest tag in production: Always use immutable image tags (git SHA or semantic version). :latest makes rollbacks impossible and deployments non-deterministic.
• One giant cluster per account: Use separate clusters per environment (dev/staging/prod) or per team. Cluster-level IAM and capacity provider strategies are easier to manage.
• Oversized task definitions: Right-size CPU and memory. A 4 vCPU / 8 GB task running at 10% utilization is burning money. Start small, scale up based on CloudWatch Container Insights metrics.
• Skipping health checks: Always define container health checks in the task definition AND target group health checks. Without both, ECS cannot detect unhealthy tasks.
• Ignoring ECS Exec: Enable ExecuteCommandConfiguration on the cluster and enableExecuteCommand on the service. It replaces SSH access to containers and is essential for debugging.
• No deployment circuit breaker: Without it, a bad deployment will keep cycling failing tasks indefinitely, consuming capacity and generating noise.
• Putting secrets in environment variables: Use the secrets field with Secrets Manager or SSM Parameter Store references. Environment variables are visible in the console and API.
• Running as root: Set user in the task definition to a non-root user. Combine with readonlyRootFilesystem for defense in depth.

Additional Resources

Reference Files

For detailed documentation and decision guidance, consult:

• `references/express-mode.md` — Full Express Mode pros/cons, defaults table, IAM roles, CLI commands, resource sharing details, Express Mode vs standard ECS decision matrix, and official AWS documentation links

Amazon ECS Express Mode — Detailed Reference

ECS Express Mode provisions a complete production application stack from a single API call requiring only three parameters: a container image, task execution role, and infrastructure role. No additional charge beyond the underlying AWS resources. AWS recommends Express Mode as the migration path from App Runner (closing to new customers April 30, 2026).

Pros

• 3-parameter deployment — Container image, execution role, infrastructure role. Everything else gets sensible defaults.
• Production-ready from day one — Canary deployments, AZ rebalancing, auto-scaling (CPU/memory/request count), health checks, HTTPS with auto-provisioned ACM certificate, CloudWatch logging — all configured automatically.
• Full ECS underneath — All underlying resources (service, task definition, ALB, security groups, scaling policies) are created in your account and remain directly accessible. Customize any resource after creation without leaving Express Mode.
• ALB sharing across services — Up to 25 Express Mode services in the same VPC share an ALB via host-header routing, significantly reducing per-service cost. Express Mode auto-provisions and deprovisions ALBs as services are added/removed.
• Cluster sharing — Express Mode services can coexist in the same cluster with standard ECS services.
• IaC support — Available via Console, CLI, SDKs, CloudFormation, Terraform, and the AWS Labs MCP Server for ECS.
• No vendor lock-in risk — Unlike App Runner, Express Mode is just ECS. "Eject" to standard ECS management at any time by managing the underlying resources directly.

Cons / Limitations

• HTTP/HTTPS workloads only — Express Mode provisions an ALB and expects HTTP traffic. Not suitable for TCP/UDP services (use NLB + standard ECS), queue workers, batch jobs, gRPC without HTTP/2, or non-web workloads.
• Fargate only — No EC2 launch type. Rules out GPU instances, Graviton selection, host-level access, Docker-in-Docker, EBS volume mounts, or custom AMIs.
• Canary deployment locked — Deployment strategy is set to Canary and cannot be changed after creation. No rolling update or Blue/Green (CodeDeploy) option.
• Load balancer config immutable — Load balancer configurations cannot be updated on Express Mode services. If NLB, custom listener rules, or multi-protocol support is needed, use standard ECS.
• Service name and cluster immutable after create — Cannot be changed on updates.
• Subnet lock-in per VPC — The first Express Mode service in a VPC defines the subnets for that VPC's shared ALB (internet-facing or internal). Subsequent services must match those AZs.
• Single container only — No sidecar support in the Express Mode API. Envoy proxies, log routers, or datadog agents as sidecars require editing the task definition directly after creation.
• Default VPC requirements — If no subnets are specified, requires a default VPC with at least two public subnets in two AZs with at least 8 free IPs per CIDR block per subnet.
• x86_64 Linux only by default — Defaults to X86_64 architecture on Linux. ARM/Graviton requires post-creation task definition changes.
• Container name sensitivity — The default container is named "Main". Renaming it can break Express Mode's ability to manage subsequent updates via the Express Mode Console or APIs.

Defaults Table

All underlying resources remain accessible for direct management.

Resources Created by Express Mode

Express Mode automatically provisions and configures:

• ECS default cluster (if not already existing) with Fargate capacity providers
• Task definition with container, logging, and networking configurations
• Service with canary deployment and auto-scaling
• Application Load Balancer with HTTPS listener, listener rules, and target groups
• Security groups with minimal required ingress (service SG + LB SG)
• Service Linked Roles for auto-scaling and load balancing
• Application Auto Scaling scalable target and target tracking scaling policy
• CloudWatch Log group specific to the service
• Metric alarm for detecting faulty deployments
• ACM certificate for HTTPS

Resource Sharing and Cost Optimization

• Load balancer sharing — Up to 25 Express Mode services in the same VPC share an ALB. Express Mode auto-provisions additional ALBs as needed and deprovisions unused ones as services are removed.
• Cluster sharing — Express Mode services can be grouped in ECS Clusters alongside standard (non-Express) ECS services.

IAM Roles

Auto-created service-linked roles: ecsServiceRoleForECS, AWSServiceRoleForElasticLoadBalancing, AWSServiceRoleForApplicationAutoScaling_ECSService.

CLI Commands

# Create an Express Mode service (minimal — 3 required params)
aws ecs create-express-gateway-service \
  --execution-role-arn arn:aws:iam::role/ecsTaskExecutionRole \
  --infrastructure-role-arn arn:aws:iam::role/ecsInfrastructureRoleForExpressServices \
  --primary-container 'image=nginx'

# Create with custom scaling, port, and service name
aws ecs create-express-gateway-service \
  --execution-role-arn arn:aws:iam::role/ecsTaskExecutionRole \
  --infrastructure-role-arn arn:aws:iam::role/ecsInfrastructureRoleForExpressServices \
  --primary-container 'image=my-app:v1,port=8080' \
  --scaling-target '{"minTaskCount": 2}' \
  --service-name my-api

# Monitor an Express Mode deployment (interactive terminal UI)
aws ecs monitor-express-gateway-service \
  --service-arn arn:aws:ecs:us-east-1:123456789012:service/my-cluster/my-svc

# Monitor with custom timeout (default 30 min)
aws ecs monitor-express-gateway-service \
  --service-arn my-express-gateway-service \
  --timeout 60

# Delete an Express Mode service and its managed resources
aws ecs delete-express-gateway-service --service <service-name-or-arn>

When to Use Express Mode vs Standard ECS

Official Documentation

• Amazon ECS Express Mode Overview
• Resources created by Express Mode
• Creating an Express Mode service
• App Runner to Express Mode migration
• CLI: create-express-gateway-service
• CLI: monitor-express-gateway-service
• CLI: delete-express-gateway-service