aws ecs run-task: Run a One-Off ECS Task in CI
aws ecs run-task starts a standalone ECS task from a task definition, the standard way to run database migrations or batch jobs in a pipeline without a long-lived service.
Deploy pipelines run migrations as a one-off task before shifting traffic. run-task on Fargate needs explicit networking, and the most common failure is a malformed network configuration or a missing PassRole.
What it does
aws ecs run-task launches --task-definition once on --cluster with the given --launch-type. On FARGATE you must supply --network-configuration (subnets, security groups, public-IP setting). --overrides lets you change the command or environment for this run, for example to run a migrate command.
Common usage
aws ecs run-task \
--cluster prod \
--task-definition my-app-migrate:12 \
--launch-type FARGATE \
--network-configuration 'awsvpcConfiguration={subnets=[subnet-0123],securityGroups=[sg-0123],assignPublicIp=DISABLED}' \
--overrides '{"containerOverrides":[{"name":"app","command":["python","manage.py","migrate"]}]}' \
--query 'tasks[0].taskArn' --output textOptions
| Flag | What it does |
|---|---|
| --cluster <name> | Cluster to run on (default cluster if omitted) |
| --task-definition <family:rev> | Task definition to run (required) |
| --launch-type FARGATE|EC2 | Capacity type |
| --network-configuration awsvpcConfiguration={..} | Subnets/SGs (required for Fargate) |
| --overrides {..} | Override command/env for this run |
| --count <n> | Number of task copies to launch |
In CI
run-task is async: it returns once the task is accepted, not when it finishes. Capture the taskArn, then aws ecs wait tasks-stopped and check the container exitCode (a failed migration can still report a "successfully launched" task). On a private subnet, set assignPublicIp=DISABLED and ensure a NAT or VPC endpoints exist, or image pulls hang.
Common errors in CI
"An error occurred (InvalidParameterException) when calling the RunTask operation: Network Configuration must be provided when networkMode 'awsvpc' is specified" means you omitted --network-configuration on a Fargate/awsvpc task. "AccessDeniedException ... is not authorized to perform: iam:PassRole" means the task or execution role cannot be passed; add iam:PassRole. A task that stops immediately with "CannotPullContainerError" means no route to the registry (NAT/VPC-endpoint or public IP missing).