Amazon ECS Task Definitions: The Operating Manual Every Food Truck Follows
A container image packages the food truck. An Amazon ECS task definition tells ECS how that truck should operate.
The Business Goal
In the last chapter, Amazon ECS became the operations manager for our food truck business.
It kept the right number of trucks running.
But ECS kept saying things like:
“Run this task.”
“Create a task definition.”
Naturally, the next question is:
If I already have a container image, why do I need a task definition?
The Story
Imagine you just bought twenty identical food trucks.
Tomorrow, you hire twenty new employees.
Immediately, the questions begin:
- Which menu are we serving?
- Which window should customers order from?
- How many people work this truck?
- What powers the truck?
- Where do today’s sales reports go?
- How do we open and close?
If every employee answers differently, every truck operates differently.
Consistency disappears.
Chaos begins.
Meet the Task Definition
The owner solves the problem with one laminated standard operating procedure.
Truck Name: Payments
Truck Blueprint: payments:v12
Staff Required: 2
Serving Window: Left Side
Power: 220V / 20A
Logs: Send to Headquarters
Opening Command: Start Payments
Nobody guesses.
Each truck launched from this version of the manual receives the same operating instructions.
That operating manual is an Amazon ECS task definition.
Core idea: A task definition is a versioned blueprint that describes the containers and runtime settings for an ECS task.
A Task Definition Is a Contract
Think of a task definition as the contract between your application and Amazon ECS.
You declare how the application should run. ECS uses that declaration when it places and starts a task on compatible capacity.
The same ECS task-definition model applies whether the task runs on self-managed EC2 capacity or AWS Fargate.
How It Works
What a Task Definition Describes
A task definition can answer questions such as:
- Which container image should ECS pull?
- How much CPU and memory does the task or container require?
- Which ports should the container expose?
- Which environment values or secrets should be injected?
- Where should logs go?
- Which command should start the application?
- Which IAM roles should the task use?
Key rule: A task definition does not run an application by itself. It describes how ECS should create a task.
Why This Is Not All Inside the Image
The same food truck can operate in different situations.
A neighborhood event might need one set of operating limits. A music festival might need another.
The truck image can remain unchanged while the operating instructions vary by environment.
Likewise, the same container image can appear in different task-definition revisions with different CPU, memory, logging, IAM, networking, or startup settings.
Image vs. Task Definition vs. Task
| In the story | In AWS | What it means |
|---|---|---|
| Food truck blueprint | Container image | Packages the application and its dependencies |
| Operating manual | Task definition | Describes how ECS should run one or more containers |
| Operating food truck | Task | A running instance of a task definition |
Container Image
+
Task Definition
|
v
Running Task
How Amazon ECS Uses It
You register a task definition, creating a numbered revision.
An ECS service can then use that revision to maintain several tasks with the same declared configuration.
+-- Task 1
+-- Task 2
Task Definition -+-- Task 3
Revision +-- Task 4
+-- Task 5
+-- Task 6
One operating-manual revision.
Six tasks launched from the same instructions.
Updating the Operating Manual
Suppose you change the logging configuration.
ECS task-definition revisions are immutable. Instead of editing the existing revision, you register a new one.
Existing tasks continue using the revision that launched them. To apply the new instructions, update the ECS service to use the new revision and deploy replacement tasks.
Standardization scales, but revision rollout is still an explicit deployment decision.
Architectural Mapping
Container Image
|
v
Task Definition Revision
Image + CPU + Memory + Ports + Roles + Logs
|
v
ECS Service or RunTask request
|
v
Running ECS Task
|
v
EC2 capacity or AWS Fargate
The image supplies the packaged application. The task definition supplies its ECS runtime contract. A service or task request uses that contract to create a running task on compatible capacity.
When to Use It
Use an ECS task definition when:
- running containers with Amazon ECS
- declaring CPU, memory, ports, commands, logging, or environment settings
- assigning task and task-execution IAM roles
- launching the same container image with controlled runtime configurations
- versioning changes to an ECS workload’s runtime contract
When Not to Use It
A task definition is not:
- a container-image build file
- a running task by itself
- an ECS service that maintains a desired count
- a deployment that automatically replaces existing tasks
- a place to embed plaintext secrets directly in configuration
Painkiller
Problem: Every application task needs consistent runtime instructions. Pain: Ad hoc configuration creates drift, deployment mistakes, and security risk. AWS solution: Use a versioned ECS task definition to declare how ECS should create each task.
Knife Cut
A container image packages the food truck. A task definition writes the operating manual. A task is the truck following that manual.
The Masthead
What Actually Just Happened
| In the story | In AWS | What it actually means |
|---|---|---|
| Food truck blueprint | Container image | Packaged application filesystem and dependencies |
| Operating manual | Task definition revision | Immutable ECS runtime configuration |
| Employee following the manual | ECS agent or Fargate platform | Starts containers using the declared settings |
| Operating food truck | ECS task | Running copy of the task definition |
| Updated manual | New task-definition revision | Versioned change that must be deployed |
A Note From the Author
The operating-manual metaphor makes a task definition sound like one sheet for one container, but a task definition can describe multiple cooperating containers, volumes, roles, resource requirements, health checks, and other runtime settings.
Registering a new revision does not change existing tasks. ECS services must be updated to use the new revision, and deployment behavior depends on service settings, available capacity, health checks, and load balancer configuration. Sensitive values should come from supported secret integrations rather than plaintext environment entries in the task definition.
The Last Bite
Containers package your application.
Task definitions describe how ECS should run it.
ECS uses that versioned contract to create consistent tasks on available capacity.
Now every food truck has an operating manual.
One question remains:
Where are we going to park all these trucks?
Next chapter: AWS Fargate: The RV Resort for Your Food Trucks
The task definition describes the truck’s operating requirements.
Fargate provides capacity without requiring you to manage the EC2 parking lot.