Search Contact Us
Contact Us

AWS ECS Task Definitions: The Blueprint for Your Containers

By Juan Ahumada | December 4, 2025 | Part 2 of 4 in the AWS ECS Series

AWS ECS Series for Beginners

What is a Task Definition?

A Task Definition is like a blueprint or recipe that tells ECS exactly how to run your container. It specifies everything from what Docker image to use, to how much CPU and memory your container needs.

Real-World Analogy

Think of a Task Definition as a recipe card in our restaurant analogy from Part 1. The recipe doesn't cook the food itself - it just describes:

  • What ingredients are needed (Docker image)
  • How much of each ingredient (CPU, memory)
  • The cooking temperature (environment variables)
  • What dishes to prepare together (multiple containers)
  • How to plate the dish (port mappings)

You can use the same recipe to cook the dish multiple times. Similarly, you use one Task Definition to run multiple Tasks.

Key Components of a Task Definition

1. Container Image

This is the Docker image that ECS will run. It's typically stored in Amazon ECR (Elastic Container Registry) or Docker Hub.

Example: 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

2. CPU and Memory

You specify how much computing power and memory your container needs. This is crucial for performance and cost optimization.

  • CPU: Measured in "units" (1 vCPU = 1024 units). Common values: 256, 512, 1024
  • Memory: Measured in MB. Common values: 512, 1024, 2048

Tip: Start Small

When you're starting out, begin with smaller values like 256 CPU units and 512 MB memory. You can always increase them later based on your application's actual usage. This helps keep costs down while you're learning.

3. Port Mappings

Port mappings tell ECS how to route traffic to your container. If your web application runs on port 3000 inside the container, you map it so external traffic can reach it.

4. Environment Variables

These are configuration values passed to your container at runtime. Common uses include:

  • Database connection strings
  • API keys (though AWS Secrets Manager is better for sensitive data)
  • Application settings

5. Logging Configuration

You can configure where your container's logs go. Most commonly, logs are sent to Amazon CloudWatch Logs for easy viewing and analysis.

A Simple Task Definition Example

Here's what a basic Task Definition looks like in JSON format. Don't worry if it looks complex - AWS Console provides a user-friendly interface to create these:

// Simple Task Definition for a web application { "family": "my-web-app", "networkMode": "awsvpc", "requiresCompatibilities": ["FARGATE"], "cpu": "256", "memory": "512", "containerDefinitions": [ { "name": "web-container", "image": "nginx:latest", "portMappings": [ { "containerPort": 80, "protocol": "tcp" } ], "environment": [ { "name": "APP_ENV", "value": "production" } ] } ] }

Task Definition Revisions

Every time you update a Task Definition, AWS creates a new revision. This is like versioning for your blueprints:

  • my-web-app:1 - First version
  • my-web-app:2 - Updated with more memory
  • my-web-app:3 - Changed environment variables

This makes it easy to roll back to a previous configuration if something goes wrong.

Multiple Containers in One Task Definition

A Task Definition can include multiple containers that work together. Common patterns include:

  • Sidecar pattern: A logging container alongside your main app
  • Proxy pattern: A reverse proxy like Nginx in front of your app
  • Ambassador pattern: A container that handles external communication

All containers in a Task Definition share the same network space, so they can communicate via localhost.

Creating Your First Task Definition

The easiest way to create a Task Definition is through the AWS Console:

  1. Go to ECS Console > Task Definitions
  2. Click "Create new Task Definition"
  3. Choose your launch type (Fargate or EC2)
  4. Fill in the task name and container details
  5. Set CPU and memory limits
  6. Configure port mappings
  7. Click "Create"

Key Concepts to Remember

  • A Task Definition is a blueprint that describes how to run your containers
  • It specifies the Docker image, CPU, memory, ports, and environment variables
  • Each update creates a new revision for easy rollback
  • You can have multiple containers in one Task Definition
  • Task Definitions themselves are free - you only pay when running Tasks

What's Next?

Now that you understand Task Definitions (the blueprints), you're ready to learn about Services - the component that keeps your application running reliably. In the next article, we'll explore how Services ensure your containers are always available and automatically recover from failures.

Continue Reading

← Back to Blog