Connect to ECS Container

In one of our projects, our developers needed to access an ECS container via shell for debugging purposes without requiring access to the underlying instances, SSH, jump/bastion hosts, or public addressing. Finally, we found the solution with ECS Exec.

Requirements

ECS Exec builds upon Session Manager, another AWS service that provides the same functionality for EC2 instances, so we need the Session Manager Plugin for our AWS CLI.

On macOS, you can use Homebrew to install both:

brew install awscli
brew install session-manager-plugin

For more installation options, see the appropriate tools pages.

Preparations

In our project, all permissions were already correctly configured. But in your project, granting permission for the ECS task to connect with the SSM Session Manager service might be necessary. You should add the following policy to your existing ECS task IAM role:

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

In addition, your IAM role must have permission to execute ecs:ExecuteCommand. Add the following policy to your IAM role:

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

Last but not least, you must activate the ECS Exec feature in your existing task by using the parameter --enable-execute-command:

aws ecs update-service --cluster ${cluster-name} --service ${service-name} --enable-execute-command

aws ecs update-service --cluster staging-cluster --service staging-product-service --enable-execute-command

Connect to container

After everything is done, you can connect to the container with the following command:

aws ecs execute-command --cluster ${cluster-name} --task ${task-id} --container ${container-name} --interactive --command /bin/bash

aws ecs execute-command --cluster staging-cluster --task efbb9c1cfa5e353496345f78e3ba3962 --container staging-product-service --interactive --command /bin/bash

Further reading

If you are looking for information on actually debugging the containers, then I can recommend the following pages:

• netshoot: a Docker + Kubernetes network trouble-shooting swiss-army container
• Amazon ECS Service Connect