Skip to main content

Access ECS Container Terminal

This guide explains how to use Amazon ECS Exec to securely access a running container for interactive task management. With ECS Exec, you can open a shell inside your container for debugging or troubleshooting without needing SSH, bastion hosts, or open inbound ports.

You can connect in two ways:

  • AWS Management Console – a simple, one-click method that works directly in the ECS console.
  • AWS CLI – a scriptable, automation-friendly method using the execute-command API.

Option 1: AWS Management Console

Prerequisites​

  • ECS Exec enabled for your service or task
  • IAM role/user with ecs:ExecuteCommand permissions
  • CloudShell enabled for your AWS account
  • Supported AWS region (all commercial regions as of launch)

Steps​

  1. Open the AWS Management Console → Amazon ECS → Clusters.
  2. Select your cluster → Tasks.
  3. Choose the running task.
  4. Under Containers, select the container you want to connect to.
  5. Click Connect.
  6. The console opens a CloudShell session directly into the container.

Option 2: AWS CLI

Prerequisites​

  • AWS CLI installed and configured
  • jq installed (for parsing JSON in bash scripts)
  • AWS IAM permissions to modify ECS services and tasks
  • Homebrew installed (for macOS users)

Installation​

Install Session Manager Plugin​

The Session Manager plugin is required for the AWS CLI to start a session with your containers. Install it using Homebrew:

brew install --cask session-manager-plugin

Configuration​

IAM Permissions​

Task Role​

Add the following permissions to the task role to allow tasks to communicate with the Systems Manager service endpoints:

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

User/Role​

Ensure the user or role executing these commands has the following permission to use ECS ExecuteCommand:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "User access to ECS ExecuteCommand",
            "Effect": "Allow",
            "Action": "ecs:ExecuteCommand",
            "Resource": "*"
        }
    ]
}

Enabling Execute Command​

tip

For those utilizing Terraform, our Optimus Terraform AWS ECS Service module simplifies enabling the execute command feature on your ECS services. It's designed to integrate seamlessly into your infrastructure, ensuring best practices and efficiency. Consider leveraging this module to enhance your ECS service setup with minimal effort.

Use AWS CLI to enable the execute command feature for your service. Here's how to do it with the AWS CLI:

aws ecs update-service \
    --cluster <cluster-name> \
    --task-definition <task-definition-name> \
    --service <service-name> \
    --enable-execute-command

Connect to ECS Container​

To execute commands within a container of a specific task, follow these steps:

1. Set Environment Variables​

Set the necessary variables for your region, cluster name, service name, and container name:

REGION="ap-southeast-1"
CLUSTER_NAME="your-cluster-name"
SERVICE_NAME="your-service-name"
CONTAINER_NAME="your-container-name"

2. List Tasks and Extract Task ID​

Use the AWS CLI to list tasks for the service and extract the first task ID:

TASK_ID=$(aws ecs list-tasks \
  --region $REGION \
  --cluster $CLUSTER_NAME \
  --service-name $SERVICE_NAME \
  --query "taskArns[]" \
  --output json | jq -r '.[0]' | awk -F'/' '{print $NF}')

3. Connect​

You can try /bin/sh or /bin/bash

aws ecs execute-command \
  --region $REGION \
  --cluster $CLUSTER_NAME \
  --task $TASK_ID \
  --container $CONTAINER_NAME \
  --command "/bin/sh" \
  --interactive