Staaarter Tools

ECS Task Definition Generator

Builds an ECS task definition JSON document for FARGATE or EC2 launch types, with family name, cpu/memory, one or more container definitions (name, image, port mappings, environment variables, and an awslogs log configuration), plus executionRoleArn/taskRoleArn. A free online tool from Staaarter, right in your browser.

Runs locallyUpdated 2026-07-26
generatorawsecsfargatejson

Overview

Introduction

An ECS task definition has to get several interlocking details right at once: network mode matching the launch type, port mappings shaped correctly for Fargate vs. EC2, and a log configuration on every single container, not just the task as a whole.

This tool generates a valid task definition JSON from a small set of fields per container, with the launch-type-specific defaults (networking mode, cpu/memory requirements) applied automatically.

What Is ECS Task Definition Generator?

A generator for ECS task definition JSON documents, covering `family`, `requiresCompatibilities`, `networkMode`, `cpu`/`memory`, `executionRoleArn`/`taskRoleArn`, and one or more `containerDefinitions`.

Each container definition includes a name, image, optional port mapping, optional environment variables, and an `awslogs` log configuration pointed at a `/ecs/<family>` CloudWatch Logs group.

How ECS Task Definition Generator Works

Choosing FARGATE sets `networkMode: "awsvpc"` and requires task-level `cpu`/`memory`; choosing EC2 sets `networkMode: "bridge"` and treats cpu/memory as optional, matching how each launch type actually schedules tasks.

Each container's port mapping is built as `{ containerPort, protocol: "tcp" }` for FARGATE (awsvpc networking maps container and host ports 1:1 automatically) or `{ containerPort, hostPort, protocol: "tcp" }` for EC2 (bridge networking needs an explicit host port).

Environment variable lines (`KEY=VALUE`) are parsed per container into the `environment` array, and every container gets a `logConfiguration` block using the `awslogs` driver with a log group derived from the family name.

When To Use ECS Task Definition Generator

Use it when registering a new ECS service and you need a correctly-shaped task definition JSON to pass to `aws ecs register-task-definition` or embed in a CloudFormation/Terraform ECS resource.

It's also useful for quickly adding a sidecar container (a second container definition) alongside your main application container within the same task.

Often used alongside AWS Lambda Config Generator and EC2 User Data Generator.

Features

Advantages

  • Applies the correct networking mode and cpu/memory requirements automatically based on launch type, so Fargate-specific requirements aren't missed.
  • Wires up `awslogs` logging on every container definition by default, closing off the common mistake of a task definition with no log configuration.
  • Supports multiple containers in one task definition, covering the common main-container-plus-sidecar pattern.

Limitations

  • Only surfaces the most common fields (name, image, ports, environment, logging); ECS's full task definition schema includes many more (health checks, mount points, secrets, ulimits) not exposed here.
  • Doesn't create the referenced CloudWatch Logs group or IAM roles, only references their names/ARNs in the output.

Examples

Single-container FARGATE task definition

Input

family: my-app, launchType: FARGATE, cpu: 256, memory: 512, container: {name: app, image: my-app:latest, containerPort: 3000}

Output

{
  "family": "my-app",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "my-app:latest",
      "essential": true,
      "portMappings": [{ "containerPort": 3000, "protocol": "tcp" }],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/my-app",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ],
  "cpu": "256",
  "memory": "512"
}

FARGATE requires cpu/memory at the task level and uses awsvpc networking, so the port mapping omits hostPort (Fargate maps it 1:1 automatically).

Best Practices & Notes

Best Practices

  • Set `executionRoleArn` to a role with at least the `AmazonECSTaskExecutionRolePolicy` managed policy, without it Fargate tasks can't pull images or write logs.
  • Keep `taskRoleArn` scoped to only the AWS permissions the application inside the container actually needs, not the same role as executionRoleArn.
  • Create the referenced CloudWatch Logs group ahead of time (or via the same CloudFormation stack) so tasks don't fail to start due to a missing log group.

Developer Notes

Environment variable lines are parsed by finding the first `=` in each non-empty line and splitting there, so values containing `=` (e.g. a base64 string or connection string) are preserved intact. FARGATE-launch-type task definitions require both cpu and memory to be present at the task level per ECS's own validation, so the generator returns an error rather than silently omitting them when that combination is requested.

ECS Task Definition Generator Use Cases

  • Registering a new ECS Fargate service's task definition via the AWS CLI or SDK
  • Adding a sidecar container definition (e.g. a log shipper or proxy) alongside a main application container
  • Producing the task definition JSON to embed in a Terraform `aws_ecs_task_definition` resource's `container_definitions` field

Common Mistakes

  • Omitting cpu/memory on a FARGATE task definition, which ECS rejects at registration time since Fargate needs to know the exact capacity to provision.
  • Forgetting a log configuration entirely, leaving no way to see container output once the task is running.

Tips

  • Follow up with the Lambda Config Generator if you're comparing container-based (ECS) vs. serverless-function (Lambda) deployment for the same workload.

References

Frequently Asked Questions