If you’ve been running AWS ECS for any length of time, you’ve likely noticed something annoying: task definition revisions accumulate. Every deployment creates a new revision, and AWS never cleans up the old ones. Over years of active development, this adds up.
I recently inherited an AWS account that had been running ECS workloads for about 6 years. When I looked at the task definitions, I found over 178,000 revisions spread across various task families. The AWS Console offers no bulk delete option, so cleaning these up manually would mean clicking through each revision one by one. That’s not happening.
Why This Matters
You might think “who cares about old task definition revisions?” and that’s a fair question. Here’s the problem: if you’re using AWS Config, each of those revisions is tracked as a Configuration Item (CI). Config charges per CI recorded, and having 178,000 stale task definitions sitting around means you’re paying to track resources that serve no purpose. It also clutters your Config inventory, making it harder to find what actually matters during an audit or incident response.
The Tool
I wrote ECS Task Cleaner to solve this problem. It’s a Go CLI that lists all revisions for a given task family, keeps the N most recent ones (default is 5), and deletes everything else. Nothing fancy, but it gets the job done.
The deletion process is two-step because that’s how AWS requires it:
- Deregister each task definition (marks it as INACTIVE)
- Delete the deregistered definitions in batches
AWS limits batch deletes to 10 task definitions per API call, and you’ll hit rate limits if you go too fast. The tool handles this by waiting between batches (10 seconds by default).
Usage
The basic usage is straightforward:
ecs-task-cleaner my-task-family --profile my-aws-profile
This keeps the 5 most recent revisions and deletes everything else. You can adjust how many to keep:
ecs-task-cleaner my-task-family --profile staging --keep 10
Before running a destructive operation, you probably want to preview what will be deleted:
ecs-task-cleaner my-task-family --profile staging --dry-run
The dry-run flag shows you exactly which revisions would be deleted without actually touching anything.
The Reality of Large Cleanups
Here’s something I learned the hard way: cleaning up 178,000 task definitions takes a long time. With AWS rate limits and the 10-item batch size restriction, I was processing roughly 1,000 revisions per hour. The entire cleanup took over 120 hours.
There’s no way around this. AWS sets the rate limits, and being aggressive about it will just get your requests throttled. I ran the tool against each task family in sequence, sometimes running it overnight for the larger families. It’s tedious, but it’s still better than clicking through the Console.
CLI Options
The tool supports the options you’d expect:
| Flag | Description | Default |
|---|---|---|
--profile, -p | AWS profile to use | environment default |
--region, -r | AWS region | profile default |
--keep, -k | Number of recent revisions to keep | 5 |
--dry-run, -n | Preview without making changes | false |
--batch-size, -b | Definitions per API call (max 10) | 10 |
--wait-time, -w | Pause between batches | 10s |
Required Permissions
Your IAM user or role needs these permissions:
ecs:ListTaskDefinitionsecs:DeregisterTaskDefinitionecs:DeleteTaskDefinitions
Installation
If you have Go installed:
go install github.com/scottbrown/ecs-task-cleaner/cmd/ecs-task-cleaner@latest
Or grab a binary from the releases page.
Wrapping Up
ECS Task Cleaner won’t win any awards for innovation. It’s a simple tool that automates a tedious process AWS should probably handle themselves. But if you’re sitting on thousands of stale task definition revisions, it’ll save you from death by a thousand clicks.
The source is available on GitHub if you want to look at it or contribute.