Introduction

When you want to run containers on AWS ECS, you need to tell AWS what your container looks like and how it should run. A task definition is like a recipe that describes your container, what resources it needs, and how it connects to the network.

When you want to run a web app inside a container on AWS ECS.

When you need to specify environment variables or ports for your container.

When you want to update your container image and redeploy with new settings.

When you want to run multiple containers together as one task.

When you want to control CPU and memory limits for your container.

Config File - task-definition.json

task-definition.json

{
  "family": "my-app-task",
  "networkMode": "awsvpc",
  "containerDefinitions": [
    {
      "name": "my-app-container",
      "image": "nginx:1.23",
      "portMappings": [
        {
          "containerPort": 80,
          "hostPort": 80,
          "protocol": "tcp"
        }
      ],
      "essential": true,
      "memory": 256,
      "cpu": 128
    }
  ],
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512"
}

family: The name of this task definition group.

networkMode: How the network is set up; awsvpc means each task gets its own network interface.

containerDefinitions: Describes the container(s) to run, including image, ports, CPU, and memory.

requiresCompatibilities: Specifies this task runs on AWS Fargate, a serverless container service.

cpu and memory: Total CPU and memory for the task.

Commands

This command tells AWS ECS to create a new task definition using the details in the JSON file. It registers the recipe for your container.

Terminal

aws ecs register-task-definition --cli-input-json file://task-definition.json

Expected OutputExpected

{ "taskDefinition": { "taskDefinitionArn": "arn:aws:ecs:us-east-1:123456789012:task-definition/my-app-task:1", "family": "my-app-task", "revision": 1, "status": "ACTIVE", "requiresAttributes": [ { "name": "com.amazonaws.ecs.capability.logging-driver.awslogs" } ], "containerDefinitions": [ { "name": "my-app-container", "image": "nginx:1.23", "cpu": 128, "memory": 256, "essential": true, "portMappings": [ { "containerPort": 80, "hostPort": 80, "protocol": "tcp" } ] } ], "networkMode": "awsvpc", "requiresCompatibilities": [ "FARGATE" ], "cpu": "256", "memory": "512" } }

→

--cli-input-json - Specifies the JSON file with the task definition details.

This command lists all versions of the task definitions registered under the family name 'my-app-task'. It helps you see your task definition history.

Terminal

aws ecs list-task-definitions --family-prefix my-app-task

Expected OutputExpected

TASKDEFINITIONARNS arn:aws:ecs:us-east-1:123456789012:task-definition/my-app-task:1

→

--family-prefix - Filters task definitions by family name.

This command shows detailed information about the specific task definition version 1. Useful to verify the settings before running tasks.

Terminal

aws ecs describe-task-definition --task-definition my-app-task:1

Expected OutputExpected

{ "taskDefinition": { "taskDefinitionArn": "arn:aws:ecs:us-east-1:123456789012:task-definition/my-app-task:1", "family": "my-app-task", "revision": 1, "containerDefinitions": [ { "name": "my-app-container", "image": "nginx:1.23", "cpu": 128, "memory": 256, "essential": true, "portMappings": [ { "containerPort": 80, "hostPort": 80, "protocol": "tcp" } ] } ], "networkMode": "awsvpc", "requiresCompatibilities": [ "FARGATE" ], "cpu": "256", "memory": "512" } }

→

--task-definition - Specifies which task definition version to describe.

Key Concept

If you remember nothing else from this pattern, remember: a task definition is the detailed recipe AWS ECS uses to run your container exactly how you want.

Common Mistakes

Forgetting to specify the network mode as 'awsvpc' when using Fargate.

Fargate requires 'awsvpc' network mode to assign network interfaces properly; without it, the task won't run.

Always set "networkMode": "awsvpc" in your task definition JSON when using Fargate.

Using hostPort different from containerPort without understanding port mapping.

If ports don't match or are blocked, your container won't receive traffic as expected.

Set hostPort and containerPort to the same value unless you have a specific reason to map differently.

Not registering a new task definition version after changing the container image.

ECS will keep running the old version until you register and deploy the new task definition.