# aws ecs register-task-definition

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws ecs register-task-definition --cli-input-json file://taskdef.json creates a new revision of a task definition family. Revisions are immutable, so changing an image or environment variable means registering a new revision and pointing the service at it with update-service.

## What the command does

A task definition describes how to run containers: images, CPU and memory, ports, environment, secrets, logging, roles and volumes. Each call adds revision N+1 to the family named in `family` and returns it in `taskDefinition.taskDefinitionArn`, for example `...:task-definition/orders-api:43`. Nothing is deployed until a service or `run-task` uses that revision.

## Syntax

```
aws ecs register-task-definition --cli-input-json file://taskdef.json
```

Individual options exist too (`--family`, `--container-definitions`, `--cpu`, `--memory`, `--network-mode`, `--requires-compatibilities`, `--execution-role-arn`, `--task-role-arn`), but a JSON file is far easier to review and keep in version control.

A minimal Fargate `taskdef.json`:

```
{
  "family": "orders-api",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::123456789012:role/orders-api-task",
  "runtimePlatform": { "cpuArchitecture": "ARM64", "operatingSystemFamily": "LINUX" },
  "containerDefinitions": [{
    "name": "web",
    "image": "123456789012.dkr.ecr.eu-west-2.amazonaws.com/orders-api:1.4.2",
    "essential": true,
    "portMappings": [{ "containerPort": 8080 }],
    "environment": [{ "name": "LOG_LEVEL", "value": "info" }],
    "secrets": [{ "name": "DB_PASSWORD", "valueFrom": "arn:aws:secretsmanager:eu-west-2:123456789012:secret:orders-db" }],
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": { "awslogs-group": "/ecs/orders-api", "awslogs-region": "eu-west-2", "awslogs-stream-prefix": "ecs" }
    }
  }]
}
```

## Worked examples

**Change only the image** of the current revision and deploy it. The output of `describe-task-definition` contains read-only fields that registration rejects, so strip them:

```
aws ecs describe-task-definition --task-definition orders-api \
  --query taskDefinition --output json \
  | jq '.containerDefinitions[0].image = "123456789012.dkr.ecr.eu-west-2.amazonaws.com/orders-api:1.4.3"
        | del(.taskDefinitionArn, .revision, .status, .requiresAttributes, .compatibilities, .registeredAt, .registeredBy, .deregisteredAt)' \
  > taskdef.json
REV=$(aws ecs register-task-definition --cli-input-json file://taskdef.json \
  --query "taskDefinition.taskDefinitionArn" --output text)
aws ecs update-service --cluster prod --service orders-api --task-definition "$REV"
```

**Get a skeleton** listing every accepted field:

```
aws ecs register-task-definition --generate-cli-skeleton > skeleton.json
```

**Retire an old revision** so it is not used by mistake (running tasks are unaffected):

```
aws ecs deregister-task-definition --task-definition orders-api:12
```

## Fargate CPU and memory

| CPU units | Memory options (MiB) |
|---|---|
| 256 (.25 vCPU) | 512, 1024, 2048 |
| 512 (.5 vCPU) | 1024 to 4096 in 1024 steps |
| 1024 (1 vCPU) | 2048 to 8192 in 1024 steps |
| 2048 (2 vCPU) | 4096 to 16384 in 1024 steps |
| 4096 (4 vCPU) | 8192 to 30720 in 1024 steps |

Larger sizes exist; an invalid pair fails with `ClientException: No Fargate configuration exists for given values`.

## Gotchas

- **Execution role vs task role.** The execution role lets ECS pull images, fetch secrets and write logs; the task role is what your code uses to call AWS. Missing execution-role permissions show up as `ResourceInitializationError` or `CannotPullContainerError`.
- **Unknown parameter errors** when re-registering describe output mean you forgot to delete read-only fields.
- **Secrets are fetched at start-up.** Rotating a secret does not change running tasks; force a new deployment.
- **Use immutable tags** or digests for images so a revision always means the same code.

## Questions

### How do I register a task definition with --cli-input-json?

Put the definition in a JSON file using the register-task-definition field names, then run aws ecs register-task-definition --cli-input-json file://taskdef.json.

### How do I update the image in an ECS task definition from the CLI?

Describe the current revision, change the image with jq, delete the read-only fields, register it as a new revision and update the service to use it.

### Can I edit an existing task definition revision?

No. Revisions are immutable; every change creates a new revision number.

## When this happens away from your desk

A bad task definition revision usually surfaces as tasks failing to start just after a deploy. CloudConsole, a phone app for AWS, is built to show those failures, their reasons and logs 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 register-task-definition](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html)
- [RegisterTaskDefinition API reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html)

## Related

- [aws ecs describe-task-definition](https://cloudconsole.dev/cli/ecs-describe-task-definition)
- [aws ecs update-service](https://cloudconsole.dev/cli/ecs-update-service)
- [aws ecs run-task](https://cloudconsole.dev/cli/ecs-run-task)
- [ResourceInitializationError: unable to pull secrets or registry auth](https://cloudconsole.dev/errors/ecs-resourceinitializationerror)
- [CannotPullContainerError: pull image manifest has been retried](https://cloudconsole.dev/errors/ecs-cannotpullcontainererror)
- [aws ecs describe-services](https://cloudconsole.dev/cli/ecs-describe-services)

---

Source: https://cloudconsole.dev/cli/ecs-register-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.
