Task Definitions

The JSON blueprint that tells ECS how to run your containers.

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

A task definition is a JSON document that describes one or more containers to run together. It is versioned — each edit creates a new revision like web:3.

What it specifies

Which container image(s) to run.
CPU and memory to reserve.
Port mappings, environment variables, and secrets.
Logging configuration and the network mode.

You register a task definition once, then reference it from tasks and services.

Example

{
  "family": "web",
  "networkMode": "awsvpc",
  "requiresCompatibilities": [
    "FARGATE"
  ],
  "cpu": "256",
  "memory": "512",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "public.ecr.aws/nginx/nginx:latest",
      "essential": true,
      "portMappings": [
        {
          "containerPort": 80,
          "protocol": "tcp"
        }
      ]
    }
  ]
}

When to use it

A platform team stores versioned task definitions in source control so every production deploy maps to an auditable JSON blueprint.
A developer updates a task definition revision to bump the container image tag, triggering a rolling update when the service is refreshed.
A security team reviews task definitions to confirm that no container runs as root and that only required ports are exposed.

More examples

Task Definition JSON Blueprint

A minimal Fargate task definition JSON specifying family, network mode, CPU/memory, and one container with a port mapping.

{
  "family": "web-api",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "256",
  "memory": "512",
  "containerDefinitions": [
    {
      "name": "api",
      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/api:v2",
      "portMappings": [{"containerPort": 8080}]
    }
  ]
}

Register Task Definition from File

Registers a new revision of the task definition from a local JSON file, producing a versioned ARN.

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

Describe Latest Active Revision

Fetches the current active revision of the web-api task definition and displays its family, revision number, and resource allocations.

aws ecs describe-task-definition \
  --task-definition web-api \
  --query 'taskDefinition.{family:family,revision:revision,cpu:cpu,memory:memory}'

Discussion

Be the first to comment on this lesson.