Skip to main content
Source

This page is generated from skills/ecs-architect/references/architecture-design.md. Edit the source, not this page.

ECS Architecture Design — Task Sizing and Service Parameters

Part of: ecs-architect Purpose: Size ECS tasks and set the core service parameters once the compute model is chosen. Covers Fargate CPU/memory combinations, ephemeral storage (incl. EBS task volumes), deployment percentages, health-check grace period, deployment controller choice, and placement. Facts verified against AWS docs on 2026-07-09.

Table of Contents​

  1. Task Sizing (Fargate)
  2. Task Sizing (EC2 / Managed Instances)
  3. Ephemeral Storage and Volumes
  4. Service Parameters
  5. Service Auto Scaling (task-count scaling)
  6. Deployment Controller Choice
  7. Task Placement (EC2)
  8. Sources

Task Sizing (Fargate)​

Fargate requires CPU and memory at the task level. Only specific combinations are valid (ECS task definition differences for Fargate). (Full table below reproduced from the AWS docs — last verified 2026-07-09; the docs page is authoritative if it has since changed.)

CPUMemoryOS
256 (.25 vCPU)512 MiB, 1 GB, 2 GBLinux
512 (.5 vCPU)1–4 GB (1 GB steps)Linux
1024 (1 vCPU)2–8 GB (1 GB steps)Linux, Windows
2048 (2 vCPU)4–16 GB (1 GB steps)Linux, Windows
4096 (4 vCPU)8–30 GB (1 GB steps)Linux, Windows
8192 (8 vCPU)16–60 GB (4 GB steps) — requires Linux PV 1.4.0+Linux
16384 (16 vCPU)32–120 GB (8 GB steps) — requires Linux PV 1.4.0+Linux
32768 (32 vCPU)60 GB, 120 GB, 244 GB — requires Linux PV 1.4.0+Linux

Notes:

  • The largest Fargate task is 16 vCPU / 120 GB in the general table; 32 vCPU with 60/120/244 GB is also available on Linux PV 1.4.0+. Anything larger, or GPU, must go to EC2/Managed Instances.
  • CPU can be given in units (1024) or vCPUs (1 vCPU); memory in MiB (3072) or GB (3 GB).
  • Windows containers on Fargate have a narrower set of combinations.
  • Right-size to the P95 of real usage, not peak — over-provisioning Fargate is a direct dollar cost (see ecs-cost-intelligence).

Task Sizing (EC2 / Managed Instances)​

On EC2 you can set CPU/memory at the task level and/or the container level. Task-level limits cap the whole task; container-level cpu (shares) and memory/memoryReservation (hard/soft limits) control per-container allocation and bin-packing.

  • Hard vs soft memory: memory is a hard cap (container is killed if exceeded — a common OOM cause); memoryReservation is a soft floor used for placement. Set both thoughtfully; a hard limit too close to real usage causes OOM kills.
  • Bin-packing: size tasks so an integer number fit the chosen instance type with minimal waste. This interacts with the mixed-ASG constraint — keep one resource profile per ASG.
  • Managed Instances handles instance selection/placement for you; you still size the task.

Ephemeral Storage and Volumes​

  • Fargate ephemeral storage — each task gets a default 20 GiB, expandable up to 200 GiB (minimum settable value 21 GiB) via the task-definition ephemeralStorage parameter (Linux PV 1.4.0+ / Windows PV 1.0.0+). (Fargate task ephemeral storage)
  • Amazon EBS task volumes (high-IOPS per-task block storage) — GA since Jan 2024, ECS attaches and manages one EBS volume per task at deployment time. Supported on Fargate (Linux PV 1.4.0+ — not Fargate Windows), EC2 (Nitro-based instances; ECS-optimized AMI 20231219+ for Linux, 20241017+ for Windows), and ECS Managed Instances (Linux only). Use it for data-intensive/transaction-intensive workloads that need block storage with specific IOPS/throughput, and for snapshot-seeded scratch (configure a new volume from an existing snapshot, optionally with volumeInitializationRate). Key gotcha: for tasks managed by a service the volume is always deleted on task termination — deleteOnTermination=false (preserve) is only honored for standalone tasks. Requires an infrastructure IAM role and the ECS deployment controller (rolling or blue/green). (Use Amazon EBS volumes with ECS · EBS volume termination policy)
  • Amazon EFS (shared/persistent across tasks) — for state shared across tasks; PV 1.4.0 added Fargate EFS support. (FargatePlatformVersion — 1.4 features)
  • EC2 tasks can also use bind mounts, Docker volumes, and (for EC2/Windows) FSx for Windows File Server.
  • Choose EFS for shared state across tasks, EBS for high-IOPS single-task block storage; don't rely on ephemeral storage surviving task replacement.

Service Parameters​

ParameterWhat it controlsDesign guidance
minimumHealthyPercentFloor of running/desired tasks kept healthy during a rolling deployment100% for zero-capacity-loss during deploys (needs headroom); lower (e.g. 50%) trades availability for fewer spare tasks
maximumPercentCeiling of running tasks during a deployment200% lets a full parallel set start before old ones drain; constrain if capacity/cost is tight
healthCheckGracePeriodSecondsGrace window before ELB health checks can mark a task unhealthy and kill itSet to longer than real cold-start time for slow-starting apps, or healthy tasks get killed in a restart loop
deploymentCircuitBreakerAuto-rollback on failed deploymentsEnable for services; pairs with health checks (mechanics live in ecs-devops)
enableExecuteCommandECS Exec shell into a running taskUseful for debugging; gate with IAM (see ecs-security)
availabilityZoneRebalancingECS continuously monitors task distribution across AZs and automatically starts tasks in under-populated AZs / stops them in over-populated ones (new tasks reach HEALTHY/RUNNING before old ones stop)Auto-enabled since Sept 5, 2025 for eligible services — CreateService now defaults it to ENABLED (on UpdateService an unset value keeps the existing setting, or DISABLED if never set). Not available for: Daemon strategy, EXTERNAL launch type, maximumPercent = 100, Classic Load Balancers, or an ecs.availability-zone placement constraint; on EC2 it is best-effort across existing instances only (it won't launch new ones), and AZ spread must be the first placement strategy (or no strategy set). Rebalancing replaces tasks — churn, not just recovery — so ensure graceful shutdown handling. (ECS AZ rebalancing)

Parameter semantics (min/max healthy percent, grace period) are defined in the service definition parameters reference. (Amazon ECS service parameters) The health-check grace period is a frequent production footgun: too short and a slow-booting app never passes its first check before ELB kills it, causing a crash loop. Size it against measured startup time.

Service Auto Scaling (task-count scaling)​

Distinct from cluster capacity scaling (capacity-and-scaling.md, which scales the instances under EC2/ASG capacity providers), service auto scaling scales the number of tasks in a service via Application Auto Scaling. Both layers matter: service scaling adds tasks, cluster scaling makes room for them. Design both for EC2-backed services; on Fargate only service scaling applies (capacity is implicit). (Amazon ECS service auto scaling)

Policy types:

PolicyHow it worksUse when
Target trackingPick a metric + target value; ECS creates/manages the CloudWatch alarms and adjusts task count to hold the metric near target. Scales out fast, in gradually; scale-in is paused during a deployment.Default choice — CPU/memory utilization or ALBRequestCountPerTarget. (target tracking)
Step scalingYou define CloudWatch alarm thresholds and step adjustments.You need custom, non-proportional reactions to a specific alarm.
Scheduled scalingChange min/max capacity on a schedule (cron/rate).Predictable diurnal or business-hours patterns.
Predictive scalingAnalyzes historical load to detect daily/weekly patterns and proactively increases task count ahead of forecasted demand.Cyclical traffic, recurring batch patterns, or slow-initializing apps — scales out before the influx instead of reacting; check Region availability on the doc page. (predictive scaling)

Queue-backlog pattern (worker services): for SQS-driven workers, target-tracking on raw ApproximateNumberOfMessagesVisible scales poorly because queue depth isn't proportional to task count. Use a backlog-per-task custom metric — ApproximateNumberOfMessagesVisible / RunningTaskCount — with the target set to acceptable-latency / per-message-processing-time. (backlog-per-task metric math · ECS auto scaling using custom metrics)

Design notes: set sensible min/max task bounds; combine policies (e.g. scheduled floor + target-tracking on top); remember scale-in is suppressed during deployments; and pair service scaling with cluster capacity scaling so scaled-out tasks have somewhere to land. Deep tuning and pipeline wiring belong to ecs-devops/ecs-observability.

Resilience, multi-AZ, and multi-Region posture​

  • Multi-AZ is the default resilience unit. Spread tasks across ≥2 AZs (spread on availabilityZone on EC2, or subnets in multiple AZs on Fargate/MI) and keep availabilityZoneRebalancing on (default ENABLED on new services since Sept 5, 2025) so ECS continuously re-balances — including after an AZ event. It replaces tasks to do so; design for graceful shutdown. Check the exclusion list (Daemon, EXTERNAL, maximumPercent=100, CLB, ecs.availability-zone constraint) in the service-parameters table above. (ECS AZ rebalancing)
  • Multi-Region / DR (active-active or pilot-light across Regions, Route 53 failover, cross-Region ECR replication, data-tier replication) is a broader architecture decision — sketch it here, but the detailed DR design and RTO/RPO targets belong to a Well-Architected reliability review, not this skill.
  • Operating at scale: ECS service quotas (tasks per service, services per cluster, etc.) and Fargate task retirement (platform-version revisions retire periodically; long-running tasks get replaced) shape large designs — budget for task churn and check the relevant quotas before committing to a topology. (Fargate task retirement notifications)
  • Tenancy / cluster topology (one cluster per team vs shared, namespace strategy, account boundaries) interacts with the isolation criterion in the SKILL — for regulated multi-tenant isolation, take it to ecs-security.

Deployment Controller Choice​

This skill names which controller a model supports; ecs-devops designs the release process.

ControllerWhat it doesNotes
ECS (rolling)Default; replaces tasks per min/max healthy percentSimplest; add the circuit breaker for auto-rollback
ECS (native blue/green)ECS-native blue/green (launched July 2025): provisions a green revision on a second target group, shifts traffic all-at-once / canary / linear, holds a bake period, then retires blue or rolls back on alarm/hook failure. Works with ALB, NLB, and Service ConnectSet deploymentConfiguration.strategy to BLUE_GREEN; deployment config lives inside the ECS service itself. (ECS built-in blue/green deployments — launch)
CODE_DEPLOYBlue/green orchestrated by AWS CodeDeployPre-2025 path; still supported. Native blue/green consolidates this into ECS — see migrate CodeDeploy to ECS blue/green
EXTERNALThird-party deployment orchestrationFor custom/GitOps controllers

Choosing between native blue/green and CodeDeploy, canary/linear tuning, and pipeline wiring are ecs-devops decisions.

Task Placement (EC2)​

On EC2 only — neither Fargate nor Managed Instances supports placement strategies (both place for you with best-effort AZ spread; MI additionally honors placement constraints and launch-template requirements) (task placement) — use placement strategies and constraints:

  • Strategies: binpack (cost — pack tasks tight), spread (availability — across AZs/instances), random.
  • Constraints: distinctInstance (one task per instance), memberOf with attribute expressions (e.g. instance type, AZ, custom attributes).
  • Bin-pack on memory, not cpu (field heuristic). Container-level cpu is a soft CPU share — containers burst into unused CPU, so CPU bin-packing overcommits invisibly and can still schedule tasks onto a "full" instance; the container memory hard limit OOM-kills on breach, so memory bin-packing gives a predictable, safe density guarantee. Note this softness is at the container-share level — the task-level cpu value is itself a hard ceiling for the whole task. (task definition CPU/memory parameters)
  • Combine spread across availabilityZone for AZ resilience with binpack on memory for cost. For GPU-per-type layouts, use constraints alongside the separate-ASG pattern (ecs-genai). (task placement strategy examples)

Sources​