ECSExec allows you to login to a running Elastic Container Service (ECS) task without the need of opening additional ports or managing separate logins. ECSExec can be used with command line only and is not usable via the AWS console at the time of this publication.
The full documentation for ECSExec can be found here:
https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html
I recommend checking out the “Considerations for using ECS Exec” section in the linked documentation before continuing.
Preface
This post will cover the basics of configuring your work environment and ECS on Fargate resources to be able to utilize ECSExec. If you’re using ECS on fargate with the latest platform version, this is pretty straightforward. ECS on EC2 has some prerequisites outlined below, and is not covered in this post. Outside of these particular configurations, you may need to review the official documentation as there are quite a few “gotchas'' depending on your ECS configuration.
Prerequisites
You’ll need the following installed on the system you will be using to run ECSExec to access your ECS tasks:
- AWS CLI
- Session-Manager plugin
- If you're using Amazon EC2, you must use an Amazon ECS optimized AMI that was released after January 20th, 2021, with an agent version of 1.50.2 or greater.
- If you're using AWS Fargate, you must use platform version 1.4.0 or higher (Linux) or 1.0.0 (Windows).
- The ECS cluster name, task ID, and container name you wish to connect to.
Configure ECS Task IAM Role Permissions
Ensure your ECS Task IAM Role has permissions for performing actions against ssmmessages:*.
Configure User IAM Permissions
Ensure your user has permissions to perform ecs:ExecuteCommand.
Enable ECSExec On Your Container
To enable ECSExec on your container, you will have to update your task definition to enable ECSExec. You can add do so via AWS CLI with:
aws ecs update-service \
--cluster <cluster-name> \
--task-definition <task-definition-name> \
--service <service-name> \
--enable-execute-command \
Or by adding the executeCommandConfiguration in the task definition json:
{
"executeCommandConfiguration": {
"logging": "DEFAULT" // Options are DEFAULT, NONE, and OVERRIDE
}
}
If you’ve added it to the task definition manually, you’ll have to update the service via AWS CLI or re-deploy the container with the new task definition in the console.
Test Connectivity to Container with ECSExec
Attempt to connect to the container using the following command, replacing the --region, --cluster, --task, and --container values with your own:
Tasks running Linux:
aws ecs execute-command --region region_name \
--cluster cluster_name \
--task task_id \
--container container_name \
--command "/bin/sh" \
--interactive
Tasks running Windows:
aws ecs execute-command --region region_name \ --cluster cluster_name \
--task task_id \
--container container_name \
--command "powershell.exe" \
--interactive
You should receive a prompt with ‘Starting session with SessionId:” and you will be in the container’s terminal session.
