# aws ecs describe-task-definition

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws ecs describe-task-definition --task-definition orders-api:43 returns the full definition of that revision: containers and images, environment and secrets references, CPU and memory, ports, roles and logging. Pass just the family name to get its latest ACTIVE revision, and use --query to pull out a single field such as the image.

## What the command does

The response wraps everything in `taskDefinition`, with read-only metadata (`taskDefinitionArn`, `revision`, `status`, `registeredAt`, `registeredBy`) alongside the fields you registered. Deregistered revisions (`INACTIVE`) can still be described, which is useful when investigating what an old task ran.

## Syntax

```
aws ecs describe-task-definition --task-definition <family | family:revision | ARN> [--include TAGS]
```

## Worked examples

**What revision is a service running, and with which image?**

```
TD=$(aws ecs describe-services --cluster prod --services orders-api \
  --query "services[0].taskDefinition" --output text)
aws ecs describe-task-definition --task-definition "$TD" \
  --query "taskDefinition.containerDefinitions[].[name,image]" --output table
```

**Environment variables and secret references** (secret values are not included, only where they come from):

```
aws ecs describe-task-definition --task-definition orders-api \
  --query "taskDefinition.containerDefinitions[?name=='web'] | [0].{env: environment, secrets: secrets[].[name,valueFrom]}" \
  --output json
```

**Size and roles**:

```
aws ecs describe-task-definition --task-definition orders-api \
  --query "taskDefinition.[cpu,memory,executionRoleArn,taskRoleArn]" --output text
```

**Compare two revisions**:

```
diff <(aws ecs describe-task-definition --task-definition orders-api:42 --query "taskDefinition.containerDefinitions" --output json) \
     <(aws ecs describe-task-definition --task-definition orders-api:43 --query "taskDefinition.containerDefinitions" --output json)
```

**List recent revisions of a family**:

```
aws ecs list-task-definitions --family-prefix orders-api --sort DESC --max-items 5
```

## Answering "what changed?"

When a service starts failing after a deploy, the quickest evidence is a diff between the revision that worked and the one that does not. Take the previous revision number from the service's deployment history or from `list-task-definitions`, then compare only the parts that matter rather than the whole document, which also contains timestamps and registration metadata that always differ:

```
for r in 42 43; do
  aws ecs describe-task-definition --task-definition orders-api:$r \
    --query "taskDefinition.{cpu:cpu,memory:memory,containers:containerDefinitions[].{name:name,image:image,env:environment,secrets:secrets[].name}}" \
    --output json > rev-$r.json
done
diff rev-42.json rev-43.json
```

A changed image tag, a new or renamed environment variable, a reduced memory value or a secret that was added without a matching IAM permission accounts for most post-deploy failures. `registeredBy` on each revision tells you which identity created it.

## Fields to look at during an incident

| Field | Why it matters |
|---|---|
| `containerDefinitions[].image` | Is it the build you expect? Mutable tags can hide changes. |
| `memory` and container `memory`/`memoryReservation` | Hard limits cause exit 137 when exceeded. |
| `healthCheck` | Container health checks that are too strict cause restart loops. |
| `secrets[].valueFrom` | Wrong ARN or missing permission causes `ResourceInitializationError`. |
| `logConfiguration` | Tells you which log group to read. |
| `stopTimeout` | How long containers get to shut down before SIGKILL. |

## Gotchas

- **Family alone means latest ACTIVE revision**, not necessarily the one your service runs. Always check the service's `taskDefinition` first.
- **Environment values are visible** to anyone with `ecs:DescribeTaskDefinition`. Keep secrets in `secrets`, not `environment`.
- **Re-registering this output** requires deleting read-only fields; see [register-task-definition](https://cloudconsole.dev/cli/ecs-register-task-definition).
- **Revisions are per region.** The same family name in two regions is two unrelated sets of revisions.

## Questions

### How do I describe an ECS task definition from the CLI?

aws ecs describe-task-definition --task-definition family:revision. Without a revision you get the latest ACTIVE one.

### How do I find which task definition a service is using?

Read services[0].taskDefinition from aws ecs describe-services, then describe that ARN.

### How do I see the image of a running ECS task?

describe-tasks returns containers[].image and imageDigest for the task, which shows exactly what is running even if a tag moved.

## When this happens away from your desk

Knowing exactly what is deployed is the first question in many incidents. CloudConsole, a phone app for AWS, is built to show services, their current revisions and recent changes on a phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: ecs describe-task-definition](https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-task-definition.html)
- [DescribeTaskDefinition API reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTaskDefinition.html)

## Related

- [aws ecs register-task-definition](https://cloudconsole.dev/cli/ecs-register-task-definition)
- [aws ecs describe-services](https://cloudconsole.dev/cli/ecs-describe-services)
- [aws ecs describe-tasks](https://cloudconsole.dev/cli/ecs-describe-tasks)
- [OutOfMemoryError: Container killed due to memory usage](https://cloudconsole.dev/errors/ecs-outofmemoryerror)
- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [aws ecs execute-command](https://cloudconsole.dev/cli/ecs-execute-command)

---

Source: https://cloudconsole.dev/cli/ecs-describe-task-definition

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
