• October 21, 2026
• 14 min read

Amazon ECS — Core Concepts¶

The Object Model¶

flowchart TD
  CL["Cluster<br/>logical group, no cost by itself"] --> CP["Capacity providers<br/>FARGATE, FARGATE_SPOT,<br/>ASG, Managed Instances"]
  FAM["Task definition family<br/>orders-api"] --> REV["Revisions<br/>orders-api:1, :2, :3 (immutable)"]
  REV -- "run_task (once)" --> TASK["Task<br/>containers sharing one ENI"]
  REV -- "create_service" --> SVC["Service<br/>desired count, deployments"]
  SVC -- "keeps N alive" --> TASK
  CL --- SVC
  CP -- "provides capacity for" --> TASK
  TASK -- "execution role: pull, logs, secrets" --> ECR["ECR, CloudWatch Logs,<br/>Secrets Manager"]
  TASK -- "task role: your code" --> APP["SQS, S3, DynamoDB ..."]

Task definitions are immutable: you cannot edit revision 3, you register revision 4. A deregistered revision becomes INACTIVE, stays discoverable, and cannot start new tasks (existing ones keep running). Registering and deregistering is cheap; deleting needs a deregister first (delete_task_definitions).

Capacity: Launch Types vs Capacity Providers¶

AWS recommends capacity providers for placing work and keeping the launch type mainly to declare compatibility (requiresCompatibilities) in the task definition. A service or run_task call then names a capacity provider strategy.

Strategy rules (AWS documentation):

• A strategy has at most 20 providers, cannot mix provider types (Fargate with Auto Scaling group), and at least one provider needs weight above 0 when several are listed. The API default weight is 0 (the console uses 1).
• Only one provider may set base (tasks that must run there first); the rest are split by weight.
• AWS requires a provider to be associated with the cluster before a strategy can name it: pass capacityProviders=[...] to create_cluster or call put_cluster_capacity_providers. FARGATE and FARGATE_SPOT are provided by ECS on every cluster (you do not create them), but a cluster created through the API still has to list them.
• run_task takes either launchType or capacityProviderStrategy. With neither, the cluster's default strategy applies.
• A service can change strategy later; moving from a launch type to a strategy needs a forced new deployment.

# 1 task always on-demand, the rest 3:1 on Spot
strategy = [
    {"capacityProvider": "FARGATE", "base": 1, "weight": 1},
    {"capacityProvider": "FARGATE_SPOT", "weight": 3},
]

Fargate runs Linux on platform version 1.4.0 (LATEST resolves to it; Windows has its own numbering with LATEST = 1.0.0). You rarely set it; a new task always lands on the newest revision of that platform version.

Fargate Task Size¶

CPU and memory are set per task and must be one of the valid pairs. CPU is a string of CPU units (1024 = 1 vCPU); memory is MiB.

The AWS table also lists a 32 vCPU size; check it before relying on sizes above 16 vCPU. Windows tasks support only the 1, 2 and 4 vCPU rows. The unit test test_every_documented_size_is_accepted in the testing guide encodes this table.

• Ephemeral storage defaults to 20 GiB per task; set ephemeralStorage={"sizeInGiB": N} (21 to 200) for more. The image layers count against it.
• Container-level cpu/memory are optional on Fargate. memory is a hard limit (the container is killed when it exceeds it), memoryReservation a soft one. A container killed for memory shows exit code 137.
• ARM64: runtimePlatform={"operatingSystemFamily": "LINUX", "cpuArchitecture": "ARM64"}. All task definitions of one service must agree on the architecture, and the image must be built for it (a mismatch usually fails at start with an exec format error).

Task Definition Anatomy¶

The builder used throughout this guide (app/taskdef.py, excerpt) returns the keyword arguments for register_task_definition:

def build_task_definition(family, image, *, cpu=256, memory=512, execution_role_arn, task_role_arn,
                          region="us-east-1", log_group=None, command=None, environment=None,
                          secrets=None, port=None, health_cmd=None, stop_timeout=30, arm64=False) -> dict:
    container = {
        "name": "app", "image": image, "essential": True,
        "stopTimeout": stop_timeout,                      # seconds between SIGTERM and SIGKILL (max 120 on Fargate)
        "logConfiguration": {"logDriver": "awslogs", "options": {
            "awslogs-group": log_group or f"/ecs/{family}",
            "awslogs-region": region,
            "awslogs-stream-prefix": "app"}},
    }
    # ... command, environment, secrets, portMappings, healthCheck are added when given
    return {
        "family": family,
        "requiresCompatibilities": ["FARGATE"],
        "networkMode": "awsvpc",                          # the only mode Fargate supports
        "cpu": str(cpu), "memory": str(memory),           # strings, not integers
        "executionRoleArn": execution_role_arn,           # ECS agent: pull image, write logs, fetch secrets
        "taskRoleArn": task_role_arn,                     # your code: boto3 calls inside the container
        "runtimePlatform": {"operatingSystemFamily": "LINUX", "cpuArchitecture": "ARM64" if arm64 else "X86_64"},
        "containerDefinitions": [container],
        "tags": [{"key": "managed-by", "value": "tests"}],
    }

awslogs also accepts mode (non-blocking with max-buffer-size): with Docker log-driver semantics, the default blocking mode can stall your application's writes to stdout when CloudWatch is slow, while non-blocking mode buffers in memory and drops lines when the buffer is full.

A registered example; its container definition looks like this:

{
  "name": "app",
  "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/orders:1.4.2",
  "essential": true,
  "stopTimeout": 30,
  "logConfiguration": {"logDriver": "awslogs", "options": {"awslogs-group": "/ecs/orders-api", "awslogs-region": "us-east-1", "awslogs-stream-prefix": "app"}},
  "environment": [{"name": "LOG_LEVEL", "value": "info"}],
  "secrets": [{"name": "DB_PASSWORD", "valueFrom": "arn:aws:secretsmanager:us-east-1:123456789012:secret:orders/db-AbCdEf:password::"}],
  "portMappings": [{"containerPort": 8000, "protocol": "tcp"}]
}

Task Role vs Execution Role¶

The most common ECS permission bug: the two roles have different jobs, different principals of use and different failure symptoms.

The trust policy for both roles names the service and, as AWS recommends, pins the account to prevent the confused-deputy problem:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "ecs-tasks.amazonaws.com"},
    "Action": "sts:AssumeRole",
    "Condition": {
      "ArnLike": {"aws:SourceArn": "arn:aws:ecs:us-east-1:123456789012:*"},
      "StringEquals": {"aws:SourceAccount": "123456789012"}
    }
  }]
}

Rules of thumb: one task role per service, scoped to the queue, bucket or table it uses (policy shape in Foundations); a shared execution role per account is fine. On Fargate there is no instance profile, so a missing task role means no AWS credentials in the container. On EC2-backed capacity several tasks share a host, so containers are not a security boundary there; use Fargate when isolation matters.

Secrets and Configuration¶

The agent injects the value as an environment variable once, at task start. Rotating a secret does not change running tasks; start new ones (forceNewDeployment). If your code needs the live value, read it from Secrets Manager with the task role instead.

Tasks, Services and Scheduled Tasks¶

Task lifecycle¶

PROVISIONING (network interface being created) → PENDING (waiting for the agent) → ACTIVATING (image pull, container creation, load balancer registration) → RUNNING → DEACTIVATING (deregistering from target groups) → STOPPING (stop signal, then SIGKILL after stopTimeout) → DEPROVISIONING (network interface detached) → STOPPED. Every task has lastStatus (what the agent reports) and desiredStatus (what ECS wants). Stopped tasks stay visible to describe_tasks for at least one hour.

Error-message categories in stoppedReason include ResourceInitializationError, CannotPullContainer, OutOfMemoryError, ContainerRuntimeError and SpotInterruptionError. The full table is on the AWS page "Amazon ECS stopped tasks error messages". How to turn these fields into a pass or fail in Python is in 03.

Networking: awsvpc¶

Fargate tasks always use awsvpc: every task gets its own elastic network interface in your subnet, with its own private IP and the security groups you pass. Consequences:

• Security groups apply per task, not per host. Open only the container port to the load balancer's group, and let the load balancer's group be the source: sg-alb to sg-app on 8000.
• A networkConfiguration.awsvpcConfiguration takes up to 16 subnets and 5 security groups. Spread subnets across Availability Zones.
• assignPublicIp is DISABLED by default for services. A task in a private subnet needs a NAT gateway or VPC endpoints (ECR API and DKR, S3 gateway, CloudWatch Logs, plus Secrets Manager or SSM and ssmmessages if you use them) to pull images and write logs. A task in a public subnet needs ENABLED. "Task stuck in PENDING then CannotPullContainerError" is nearly always this.
• Inside the task, containers share the network namespace: they reach each other on localhost.

ECR Basics¶

Amazon Elastic Container Registry (ECR) stores your images. A repository URI looks like 123456789012.dkr.ecr.us-east-1.amazonaws.com/orders.

{
  "rules": [{
    "rulePriority": 1,
    "description": "keep the last 30 images",
    "selection": {"tagStatus": "any", "countType": "imageCountMoreThan", "countNumber": 30},
    "action": {"type": "expire"}
  }]
}

Push from CI after aws-actions/amazon-ecr-login (06); locally aws ecr get-login-password | docker login --username AWS --password-stdin <registry>. moto stores repositories, lifecycle policy text and images but does not expire or scan anything.

Quotas That Affect Tests and Deploys¶

The 6-vCPU default is the one that surprises test suites: a new account can run only 24 tasks of 0.25 vCPU at once; further tasks fail to start (look at failures and stoppedReason). Parallel smoke tests must stay far below it, and ECS API calls are throttled by token buckets per category (for example 100 burst and 20 per second sustained for DescribeTasks and ListTasks). Quotas are listed under Amazon ECS and AWS Fargate in Service Quotas.

Quick Rules¶

1. Declare requiresCompatibilities and use awsvpc, and give every Fargate definition a valid cpu/memory pair as strings.
2. Use capacity providers, not launch types, to place tasks; set a base of on-demand capacity if you also use Spot.
3. Keep the two roles separate: execution role for ECS, task role for your code, one task role per service.
4. Pin images immutably (Git SHA tag, immutable ECR tags) and add an ECR lifecycle policy.
5. Mark exactly the right containers essential. A crashing sidecar marked essential takes the whole task down.
6. Resolve secrets with secrets, remember they are read at start, and grant the execution role only those ARNs.
7. Plan the path to the registry: public subnet with a public IP, NAT, or VPC endpoints.
8. Read stopCode, stoppedReason, containers[].exitCode and containers[].reason together; no single field explains a stop.
9. Count vCPU against the Fargate quota before you parallelize tests.

See also¶

• Amazon ECS — Overview
• Amazon ECS — Services, Deployments & Networking
• Amazon ECS — boto3 in Python
• AWS Foundations — Credentials, IAM & Local Testing
• Amazon EC2
• Docker & Docker Compose