Introduction

In ECS, you do not literally type docker run ... on the host. Instead, you express the same intent in the task definition, usually through the container image, entryPoint, command, environment variables, and runtime overrides.

That means the practical question is: which part of a local docker run command should become ECS configuration, and which part should remain inside the image itself. The answer usually depends on whether you are replacing CMD, replacing ENTRYPOINT, or just passing arguments to the existing container process.

How docker run Maps to ECS

A local Docker command might look like this:

docker run my-app:latest --mode worker --queue emails

If the image already defines an entrypoint such as python app.py, then --mode worker --queue emails is just the command portion. In ECS, that becomes the container command array.

Example task definition snippet:

1{
2  "containerDefinitions": [
3    {
4      "name": "my-app",
5      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
6      "command": ["--mode", "worker", "--queue", "emails"]
7    }
8  ],
9  "family": "my-app-task"
10}

ECS expects an array of strings, not one shell string. That difference is the source of many configuration mistakes.

command Versus entryPoint

The most important distinction is:

• 'entryPoint replaces the image entrypoint.'
• 'command replaces the image command, or supplies arguments to the entrypoint.'

Suppose the image Dockerfile looks like this:

1FROM python:3.12-slim
2WORKDIR /app
3COPY . .
4ENTRYPOINT ["python", "app.py"]
5CMD ["--mode", "web"]

With that image:

• local docker run my-app:latest runs python app.py --mode web
• local docker run my-app:latest --mode worker overrides the CMD
• ECS command does the same thing

ECS example:

1{
2  "name": "my-app",
3  "image": "my-app:latest",
4  "command": ["--mode", "worker"]
5}

If you also need to replace the executable itself, then configure entryPoint:

1{
2  "name": "my-app",
3  "image": "my-app:latest",
4  "entryPoint": ["python", "maintenance.py"],
5  "command": ["--dry-run"]
6}

Example With ECS Overrides

A very common pattern is to keep the default task definition generic and override the command when calling run-task.

1aws ecs run-task \
2  --cluster my-cluster \
3  --launch-type FARGATE \
4  --task-definition my-app-task \
5  --network-configuration "awsvpcConfiguration={subnets=[subnet-123],securityGroups=[sg-123],assignPublicIp=ENABLED}" \
6  --overrides '{
7    "containerOverrides": [
8      {
9        "name": "my-app",
10        "command": ["--mode", "worker", "--queue", "emails"]
11      }
12    ]
13  }'

That is the ECS equivalent of changing the arguments at run time without rebuilding the image.

When Environment Variables Are Better Than Arguments

Sometimes developers try to cram all configuration into container arguments because that is how they tested locally. In ECS, environment variables are often a better fit for static configuration such as region, database URL, feature flags, or log level.

Example:

1{
2  "name": "my-app",
3  "image": "my-app:latest",
4  "command": ["--mode", "worker"],
5  "environment": [
6    { "name": "LOG_LEVEL", "value": "INFO" },
7    { "name": "AWS_REGION", "value": "us-east-1" }
8  ]
9}

Use arguments for invocation-specific behavior. Use environment variables for configuration values the process reads from its environment.

Quoting and Shell Assumptions

ECS does not run your command through a shell unless your container entrypoint explicitly launches one. That means this is wrong if you expect shell parsing:

{
  "command": ["python app.py --mode worker"]
}

That passes one string, not three separate arguments. The correct version is:

{
  "command": ["python", "app.py", "--mode", "worker"]
}

Or, if the image already defines the executable as entrypoint:

{
  "command": ["--mode", "worker"]
}

What to Keep in the Image

The cleanest image design usually puts the stable executable path in ENTRYPOINT and the default arguments in CMD. Then ECS only needs to override command when you want a different runtime mode.

That gives you three benefits:

• local docker run behaves predictably,
• ECS task definitions stay small,
• and ad hoc overrides remain easy.

If your ECS definitions are constantly replacing both entryPoint and command, the image probably is not structured very well.

Common Pitfalls

One common mistake is treating the ECS command field like a shell string instead of an argument array. That often causes the process to fail before it even starts.

Another mistake is confusing entryPoint and command, which leads to accidentally replacing the wrong part of the container startup behavior.

It is also easy to test with docker run locally and then forget that ECS overrides happen in JSON, where quoting, spacing, and array boundaries matter much more.

Finally, some teams overuse command arguments for static config that belongs in environment variables or secrets. That makes the task definition harder to read and operationally harder to manage.

Summary

• ECS does not use literal docker run syntax, but it maps the same ideas into task definition fields.
• Use command to override CMD or pass arguments to the image entrypoint.
• Use entryPoint only when you need to replace the executable itself.
• Pass arguments as a string array, not a shell command line.
• Prefer environment variables for stable configuration and command arguments for invocation-specific behavior.