Amazon ECS hosts containers atop EC2 instances.


Its configuration model considers:

  • Clusters are logical groupings of EC2 instances that can run Docker containers.
  • Nodes within the cluster are called ECS Container Instances.
  • An auto-scaling group can be used to dynamically scale the number of ECS Container Instances available to host tasks.
  • Task definitions define one or more containers, environment variables, resource limits and environment variables that make up a task. Task definitions can be assigned AWS IAM roles.
  • Services define the desired number of task instances and the target cluster.
  • Tasks can run Task Definitions in an ad hoc fashion, useful for scheduled or one-shot administrative tasks.

Getting started

The ECS-optimised Amazon Linux AMI can be used as a starting point.


Changes to an ECS Task Definition causes a graceful rolling deployment of new instances, where the new Deployment is started and becomes healthy before LB registration and termination of the previous Deployment. Task Definitions must remain backwards-compatible, at least by a single version.

ECS Container Agent

The ECS Container Agent is the orchestration software which communicates with the ECS service to determine which tasks need to be carried out. It's shipped as a Docker container image and is installed by default in the ECS-optimised AMI. The Agent's configuration is stored in /etc/ecs/ecs.config.

The Agent provides some API endpoints that may be useful when troubleshooting:

  • http://localhost:51678/v1/metadata describes the cluster configuration.
  • http://localhost:51678/v1/tasks describes tasks assigned by the ECS service to this container instance.

Resource constraints

Resources are used to constrain container schedulers:

  • CPUs, in units of 1,024 per CPU. Two containers each using 512 CPU units will consume 100% of the available units if scheduled on one ECS instance.
  • Memory is bound by two limits:
    • Memory reservations (soft limits) determine the minimum guaranteed memory for a container.
    • Memory limits (hard limits) are hard stops, after which a container may be terminated.
  • TCP and UDP port mappings; the same port can't be used twice. Dynamic port mapping with an ALB solves this by allowing the Agent to register a dynamically selected port with the ALB.

Capacity management

Auto scaling

ECS Container Instances should be drained prior to EC2 auto scaling events. To do this, use EC2 Auto Scaling Lifecycle Event Hooks to intercept "instance terminating" events and configure the lifecycle mode of the affected ECS Container Instance to DRAINING, causing the ECS service to reschedule the affected jobs.