Nov 18, 20265 min read

ECS Exec: Shell Into a Running Fargate Task

Enable ECS Exec on a Fargate service, grant the task role the SSM permissions it needs, open a shell with the AWS CLI, and lock it down with IAM conditions and session logging.

Illustration for ECS Exec: Shell Into a Running Fargate Task

A Fargate task sometimes misbehaves in a way the logs do not explain, and you want a shell inside it. There is no host to SSH into on Fargate, and opening port 22 on a task was never a good idea anyway. ECS Exec is AWS's answer: an interactive session into the container, tunneled through Systems Manager, authorized by IAM.

It takes four pieces to work: a flag on the service, permissions on the task role, a network path to SSM, and a plugin on your laptop. This guide sets up each one, then covers locking it down, since a shell in production is something you want audited.

ECS Exec at a glance

PieceWhat it isWhere people get stuck
Service flagenableExecuteCommand: true on the service or taskExisting tasks need a new deployment
Task rolessmmessages:*Channel permissionsPut on the execution role by mistake
NetworkOutbound HTTPS to SSM messages endpointsPrivate subnets with no NAT or endpoint
ClientAWS CLI plus the Session Manager pluginPlugin not installed
PlatformFargate platform version 1.4.0 or laterOld pinned platform versions

The ECS Exec documentation lists the full prerequisites, including the limits for Windows containers.

Grant the task role the SSM permissions

The SSM agent runs inside the task's container and uses the task role, not the execution role. Add this statement to the role in taskRoleArn:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssmmessages:CreateControlChannel", "ssmmessages:CreateDataChannel", "ssmmessages:OpenControlChannel", "ssmmessages:OpenDataChannel" ], "Resource": "*" } ] }

If the task has no task role yet, create one; the task role vs execution role guide explains which permissions go where.

Enable exec on the service and open a shell

Turn the flag on and force a new deployment. Tasks that were already running keep enableExecuteCommand: false until they are replaced.

~
$ aws ecs update-service --cluster prod --service api \ --enable-execute-command --force-new-deployment$ TASK=$(aws ecs list-tasks --cluster prod --service-name api \ --query 'taskArns[0]' --output text)$ aws ecs describe-tasks --cluster prod --tasks "$TASK" \ --query 'tasks[0].enableExecuteCommand'true$ aws ecs execute-command --cluster prod --task "$TASK" \ --container api --interactive --command "/bin/sh"

The CLI needs the Session Manager plugin installed locally. Your image needs a shell; distroless and scratch images have none, so exec in with a command your binary provides, or debug from a sidecar container that has tools.

--interactive is required today, and each session runs one command. For a one-off check, list variable names without values, such as with --command "sh -c 'env | sed \"s/=.*//\"'"; never print the full env output in production because it includes secret values and may be retained in ECS session logs.

Fix TargetNotConnectedException

The error means the SSM agent in the task never registered. Work through these in order:

  1. The task started before exec was enabled. Check enableExecuteCommand on the task, not the service.
  2. The task role lacks the ssmmessages actions above, or there is no task role.
  3. The subnet has no route to ssmmessages.<region>.amazonaws.com. Private subnets need a NAT gateway or an ssmmessages interface endpoint.
  4. The container exits or restarts before the agent connects.

AWS publishes the amazon-ecs-exec-checker script, which checks each of these for a given task.

Lock it down and log sessions

Anyone with ecs:ExecuteCommand on a task can read everything that task can read. Scope the permission with conditions on cluster and container name, and grant it to a break-glass role instead of every developer:

{ "Effect": "Allow", "Action": "ecs:ExecuteCommand", "Resource": "arn:aws:ecs:us-east-1:123456789012:task/staging/*", "Condition": { "StringEquals": { "ecs:container-name": "api" } } }

Configure the cluster's executeCommandConfiguration with logging: OVERRIDE and a CloudWatch Logs group or S3 bucket to record what was typed and printed. CloudTrail records the ExecuteCommand call itself, with the IAM principal and task.

Best fit: debugging a live container that logs and metrics cannot explain, with access limited to a small group and every session recorded.

Do you need exec with Encore?

Encore

Encore brings infrastructure from code, and on AWS it runs your services on Fargate or EKS in your own account, so ECS-level tooling stays available to whoever administers that account. Encore's docs do not describe an ECS Exec toggle, and most of the reasons teams reach for a shell have a more auditable path. Requests and Pub/Sub messages are captured as distributed traces with their database queries and outgoing calls, encore logs --env=prod streams structured logs, and encore db shell opens psql to an environment's database through the Encore Platform, with read-only access by default, as the database docs describe.

~
$ encore logs --env=prod$ encore db shell orders --env=prodorders=> SELECT status, count(*) FROM shipments GROUP BY status;

The database shell is the case that most often drives exec on ECS, since the database sits in a private subnet. With Encore, migrations and platform access go through Emissary, a SOCKS proxy in your environment described in the AWS infrastructure docs, so you never expose the database or add a bastion. Write access requires the --write or --admin flag, which makes the dangerous session the deliberate one.

Agents benefit from the same split: an agent debugging a production issue can read traces and logs, while credentials for the containers and the database stay outside the code it edits.

Best fit: teams who want production debugging through traces, logs and a scoped database shell, with containers that nobody needs to shell into day to day.

How to choose

Enable ECS Exec on services where live debugging is worth it, scope ecs:ExecuteCommand to a break-glass role, and log every session. Keep images that have a shell for those services, or use a debug sidecar. On Encore, start with traces, encore logs and encore db shell, and use AWS-level access only when an incident needs it.

Frequently asked questions

What is ECS Exec?

ECS Exec lets you run a command or open an interactive shell inside a running ECS container, on Fargate or EC2, through AWS Systems Manager Session Manager. You do not open inbound ports or manage SSH keys; access is controlled with IAM and can be logged to CloudWatch Logs or S3.

How do I enable ECS Exec on an existing service?

Update the service with --enable-execute-command and --force-new-deployment so new tasks start with the SSM agent channel. The task role must allow ssmmessages:CreateControlChannel, CreateDataChannel, OpenControlChannel and OpenDataChannel. ECS Exec does not work on tasks started before the update.

Why does aws ecs execute-command fail with TargetNotConnectedException?

Usually the task role is missing the ssmmessages permissions, the task was started before execute command was enabled, or the task cannot reach the SSM endpoints because a private subnet has neither a NAT gateway nor an ssmmessages VPC endpoint. The amazon-ecs-exec-checker script tests each of these.

Can I use ECS Exec with Encore on AWS?

Yes, at the AWS account level. Encore runs services as Fargate or EKS workloads in your own AWS account, and its docs do not describe an ECS Exec setting. Most of the reasons to exec are covered by Encore's request traces, encore logs --env and encore db shell, which opens psql to an environment's database with read-only access by default.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders