Overcast is alpha — behaviour and APIs may change between releases. Pin your version and read the changelog before upgrading.

overcast

ECS — Elastic Container Service

Quick start, what the task and service scheduler runs for real, awsvpc networking, volumes, secrets and logs, and the health checks and IAM that are never enforced.

Real Docker containers for standalone tasks and for services, with AWS’s deployment and awsvpc networking semantics on top.

Status: ⚠️ Partial

Quick start

export AWS_ENDPOINT_URL=http://localhost:4566

aws ecs create-cluster --cluster-name dev

aws ecs register-task-definition --family web --network-mode bridge \
  --container-definitions \
  '[{"name":"web","image":"nginx:alpine","essential":true,"memory":128}]'

aws ecs run-task --cluster dev --task-definition web
aws ecs list-tasks --cluster dev

Any credentials work; with none configured, run eval "$(overcast env)" first — see Using AWS SDKs and CLI.

What works

AreaBehaviour
TasksRunTask starts real containers when Docker is available. Without a container runtime, tasks are metadata only.
ServicesThe service scheduler places tasks the same way RunTask does — no separate metadata-only path — keeps the desired count, and replaces failures on a backoff.
DeploymentsA task-definition change starts a new deployment with its own tasks, counts and rolloutState; the superseded deployment drains and is dropped.
awsvpc networkingEvery container in a task shares one network namespace, one ENI address and one flat set of ports — so fastcgi_pass 127.0.0.1:9000 between sidecars works as on AWS.
VolumesAll four AWS shapes: scratch, host.sourcePath, dockerVolumeConfiguration and efsVolumeConfiguration, under AWS’s own legality rules.
SecretscontainerDefinitions[].secrets resolve from Secrets Manager (including a JSON key) and SSM Parameter Store at container start.
LogsThe awslogs driver ships container output to CloudWatch Logs under ECS’s own stream naming.
Load balancersA service with loadBalancers registers and deregisters its tasks in the target group, so ApplicationLoadBalancedFargateService serves.
ECR images{account}.dkr.ecr.{region}.amazonaws.com/{repo}:{tag} is pulled from the registry Overcast serves, with the credentials GetAuthorizationToken issues.
Hot reloadA scratch volume can be backed by a directory on your machine, so a save is live on the next request.

Differences from AWS

AreaOn AWSOvercast
Health checksContainer and target-group health checksNone. Staying RUNNING for a settle window is the only evidence of health.
Circuit breaker rollbackRedeploys the last known-good deploymentrollback is accepted and echoed, never acted on
IAMEnforcedTask and execution roles are stored, never enforced
Port collisionsEach awsvpc task has its own ENIA hostPort is published on the one Docker host, so two deployments contend for it
Capacity providers, placement constraints, service discoveryEnforcedAccepted and ignored

Every divergence, the volume rules and what a VPC placement restricts are in Limitations; the rollout arithmetic, the settle window and the circuit breaker are in Scheduler.

Gotchas

Warning

A service whose task definition maps a hostPort cannot roll out on the defaults (maximumPercent: 200), because the replacement needs the port the old task still holds. Set maximumPercent: 100 with minimumHealthyPercent: 0 to deploy stop-then-start instead — see Scheduler.

The other common stall is a service that places no task at all.

Important

networkConfiguration is required whenever the task definition’s networkMode is awsvpc, not whenever launchType is FARGATE. CDK v2’s FargateService carries the launch type in a capacityProviderStrategy and omits launchType entirely, so a check keyed on the launch type never fires.

Operations

40 of 48 listed operations are implemented. Per-operation status, notes and AWS API links: ECS operations.