Container Definitions
Each container inside a task is described by a container definition.
The containerDefinitions array is the heart of a task definition. Each entry configures one container.
Key fields
- name — unique within the task.
- image — the image URI to pull.
- essential — if
true, the whole task stops when this container stops. - command / entryPoint — override the image defaults.
A task can hold multiple containers that share a network and lifecycle — for example an app plus a logging sidecar.
Example
{
"containerDefinitions": [
{
"name": "app",
"image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:1.4",
"essential": true,
"command": [
"node",
"server.js"
],
"portMappings": [
{
"containerPort": 3000
}
]
},
{
"name": "log-router",
"image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:stable",
"essential": false
}
]
}When to use it
- A service adds a sidecar container definition for an Envoy proxy so all egress traffic is routed through a service mesh without changing application code.
- A team defines an init container that runs database migrations before the main application container starts.
- An ops team sets memory limits per container definition so a runaway process in one container cannot starve its siblings in the same task.
More examples
Two Containers in One Task
Defines two containers in one task: an essential app container and a non-essential Fluent Bit log-routing sidecar.
"containerDefinitions": [
{
"name": "app",
"image": "my-app:latest",
"portMappings": [{"containerPort": 8080}],
"memory": 384,
"essential": true
},
{
"name": "log-router",
"image": "fluent/fluent-bit:latest",
"memory": 64,
"essential": false
}
]Container Dependency Ordering
Tells ECS to wait until the init-migrate container exits successfully before starting the app container.
{
"name": "app",
"image": "my-app:latest",
"dependsOn": [
{"containerName": "init-migrate", "condition": "SUCCESS"}
]
}Hard and Soft Memory Limits
Sets a hard limit (512 MB — container is killed if exceeded) and a soft reservation (256 MB — used for scheduling decisions).
{
"name": "api",
"image": "my-api:latest",
"memory": 512,
"memoryReservation": 256
}
Discussion