• October 21, 2026
• 9 min read

Amazon ECS — Containers on Fargate, Services & Testing¶

Amazon Elastic Container Service (ECS) is AWS's own container orchestrator. You describe a container in a task definition, then either run it once (a task: a migration, a batch job, a test harness) or keep N copies alive behind a load balancer (a service). The compute underneath comes from capacity providers: Fargate and Fargate Spot (serverless, you never see a host), Auto Scaling groups of EC2 instances you manage, or ECS Managed Instances (EC2 that AWS manages for you). There is no cluster software to install or upgrade.

This guide is for Python developers and QA engineers who deploy containers to ECS, call it from code, and test against it, not for people designing VPCs. It covers the objects and the vocabulary, services and deployments, the boto3 API with its surprises (HTTP 200 with failures), patterns for FastAPI and queue-worker containers, and how to test all of it without an AWS account. Sessions, credentials, retries and ClientError handling are in AWS Foundations and are not repeated here. Docker basics are in the Docker guide.

Where ECS Fits¶

flowchart LR
  DEV["git push<br/>CI job"] -- "docker push" --> ECR["Amazon ECR<br/>repository orders"]
  ECR -. "image pull<br/>(execution role)" .-> T
  TD["task definition<br/>orders-api:8"] --> SVC["ECS service<br/>desired count 2"]
  SVC --> T
  subgraph CAP["capacity provider"]
    T["task = containers + 1 ENI<br/>FARGATE / FARGATE_SPOT / ASG / Managed Instances"]
  end
  ALB["Application Load Balancer<br/>target group + health check"] --> T
  T -- "awslogs driver" --> CWL["CloudWatch Logs<br/>/ecs/orders-api"]
  T -- "task role credentials" --> AWS["SQS, S3, Secrets Manager ..."]
  TESTS["pytest suite"] -- "run_task / describe_tasks" --> SVC

• Task definition is an immutable, versioned blueprint (family:revision): images, CPU and memory, roles, ports, logging. Registering the same family again creates a new revision.
• Task is one running copy of a task definition (one or more containers that start and stop together). A standalone task runs once; a service replaces its tasks when they die and rolls out new revisions.
• Two IAM roles are involved and are not interchangeable: the execution role (ECS pulls the image, writes logs, reads secrets) and the task role (your code calls AWS). See 01.
• Tests run against moto for control-plane logic and against the container image itself for behaviour; a small real-account smoke job covers the rest (05, 06).

Section Map¶

Minimal Working Example¶

A one-off task end to end: register a definition, run it on Fargate, wait, read the exit code. Against moto it needs no account; against AWS the same calls need a real cluster, subnet and security group.

# uv add boto3 "moto[ecs,ec2]"
import boto3
from moto import mock_aws

with mock_aws():                                             # in-process fake ECS and EC2; no account, no network
    ecs = boto3.client("ecs", region_name="us-east-1")
    ec2 = boto3.client("ec2", region_name="us-east-1")
    subnet = ec2.describe_subnets()["Subnets"][0]["SubnetId"]                       # moto ships a default VPC
    group = ec2.describe_security_groups()["SecurityGroups"][0]["GroupId"]

    ecs.create_cluster(clusterName="qa")
    task_def = ecs.register_task_definition(
        family="hello",
        requiresCompatibilities=["FARGATE"],
        networkMode="awsvpc",                                # the only mode Fargate supports
        cpu="256", memory="512",                             # task size: must be a valid Fargate pair
        containerDefinitions=[{
            "name": "app", "image": "public.ecr.aws/docker/library/busybox:1.37", "essential": True,
            "command": ["echo", "hello"],
            "memory": 256,                                   # optional on real Fargate; moto run_task needs it (see 06)
        }],
    )["taskDefinition"]
    print("registered", task_def["family"], "revision", task_def["revision"], task_def["status"])

    resp = ecs.run_task(
        cluster="qa", taskDefinition="hello:1", count=1,
        capacityProviderStrategy=[{"capacityProvider": "FARGATE", "weight": 1}],
        networkConfiguration={"awsvpcConfiguration": {"subnets": [subnet], "securityGroups": [group], "assignPublicIp": "DISABLED"}},
    )
    assert not resp["failures"], resp["failures"]            # HTTP 200 does not mean the task was placed
    task_arn = resp["tasks"][0]["taskArn"]
    print("started", resp["tasks"][0]["lastStatus"])

    ecs.get_waiter("tasks_stopped").wait(cluster="qa", tasks=[task_arn], WaiterConfig={"Delay": 1, "MaxAttempts": 20})
    task = ecs.describe_tasks(cluster="qa", tasks=[task_arn])["tasks"][0]
    print("stopped", task["lastStatus"], [(c["name"], c["exitCode"]) for c in task["containers"]])

registered hello revision 1 ACTIVE
started RUNNING
stopped STOPPED [('app', 0)]

Against a real account remove mock_aws() and pass your own cluster, subnet and security group; the task needs a way to pull the image (a public IP in a public subnet, a NAT gateway or VPC endpoints) and an executionRoleArn once it logs or uses private ECR. A real task also takes tens of seconds to start; moto "runs" it instantly and always reports exit code 0 (06).

ECS vs EC2 vs Kubernetes vs Lambda¶

Pick ECS on Fargate when the work is "run this image, keep it healthy, scale it" and nobody wants to manage nodes. Pick Lambda when handlers are short and event-driven (see SQS with Lambda); pick Kubernetes for portability and its tooling; pick EC2 when you need the instance itself.

What Changed Recently¶

Tutorials written before 2025 describe a smaller ECS. As of October 2026 (AWS documentation, AWS What's New and the current botocore model):

The current botocore model also exposes CreateGateway, CreateDaemon and the *ServiceDeployment* operations; this guide covers the stable core and mentions the newer pieces only where a test or deployment touches them. moto implements none of the newer operations (06).

Quick Rules¶

1. Pin the image by tag or digest (a Git SHA tag, immutable in ECR), never latest. A task definition revision should always mean the same bytes.
2. Set both roles on purpose. The execution role pulls the image, writes logs and reads secrets; the task role is what your code runs as. Missing the first fails before your code starts, missing the second fails with AccessDenied inside it.
3. Treat run_task as "asked", not "started". It returns HTTP 200 with a failures list; check it, then wait, then read exitCode and stopCode.
4. Wait with waiters (tasks_running, tasks_stopped, services_stable) and an explicit WaiterConfig, and stop the task in finally: a forgotten Fargate task is billed.
5. Handle SIGTERM and set stopTimeout. ECS sends SIGTERM, then SIGKILL after stopTimeout (default 30 s, maximum 120 s on Fargate). Use the exec form of CMD so your process is PID 1.
6. Turn on the deployment circuit breaker with rollback, give the service a health check grace period that covers your start-up time, and verify the new version after the deploy.
7. Keep secrets out of environment. Use secrets with a Secrets Manager or SSM valueFrom; the execution role needs read access.
8. Log to stdout with the awslogs driver and set a retention period on the log group.
9. Validate task definitions in CI (size pairs, roles, logging, no plaintext secrets) before they reach ECS, and unit-test the failure paths with Stubber.
10. Trust moto for control-plane logic only. It never runs a container, never schedules service tasks and never validates a task definition; keep a small smoke test on a real cluster.

See also¶

• Digital Garden: Knowledge Base
• AWS — Service Guides for Python & Test Automation
• AWS Foundations — boto3, Credentials & Local Testing
• Amazon EC2
• Amazon SQS — Queues, Consumers & Testing
• Amazon SNS — Topics, Subscriptions & Fan-out
• Docker & Docker Compose
• Kubernetes
• CI/CD Approaches
• FastAPI
• Pytest — Python Testing Framework