Amazon ECS Exec, you can directly interact with containers without needing to first interact with the host container operating system, open inbound ports, or manage SSH keys. You can use ECS Exec to run commands in or get a shell to a container running on an Amazon EC2 instance or on AWS Fargate.

You can run commands in a running Linux container using ECS Exec from the Amazon ECS API, AWS Command Line Interface (AWS CLI), AWS SDKs, or the AWS Copilot CLI. For details on using ECS Exec, as well as a video walkthrough, using the AWS Copilot CLI

You can also use ECS Exec to maintain stricter access control policies and audit container access. By selectively turning on this feature, you can control who can run commands and on which tasks they can run those commands. With a log of each command and their output, you can use ECS Exec to audit which tasks were run and you can use CloudTrail to audit who accessed a container.

Considerations for using ECS Exec

For this topic, you should be familiar with the following aspects involved with using ECS Exec:

• ECS Exec is only supported for Linux containers and the following Windows Amazon ECS Optimized AMIs (with the container agent version 1.56 or later):
  • Amazon ECS-optimized Windows Server 2022 Full AMI
  • Amazon ECS-optimized Windows Server 2022 Core AMI
  • Amazon ECS-optimized Windows Server 2019 Full AMI
  • Amazon ECS-optimized Windows Server 2019 Core AMI
  • Amazon ECS-optimized Windows Server 2004 Core AMI
  • Amazon ECS-optimized Windows Server 20H2 Core AMI
• ECS Exec is not currently supported using the AWS Management Console.
• If you are using interface Amazon VPC endpoints with Amazon ECS, you must create the interface Amazon VPC endpoints for Systems Manager Session Manager. For more information, see Create the Systems Manager endpoints.
• You can’t enable ECS Exec for existing tasks. It can only be enabled for new tasks.
• When a user runs commands on a container using ECS Exec, these commands are run as the root user. The SSM agent and its child processes run as root even when you specify a user ID for the container.
• The ECS Exec session has a default idle timeout time of 20 minutes. For more information, see see Specify an idle session timeout value in the AWS Systems Manager User Guide.
• The SSM agent requires that the container file system is able to be written to in order to create the required directories and files. Therefore, making the root file system read-only using the readonlyRootFilesystem task definition parameter, or any other method, isn’t supported.
• Users can run all of the commands that are available within the container context. The following actions might result in orphaned and zombie processes: terminating the main process of the container, terminating the command agent, and deleting dependencies. To cleanup zombie processes, we recommend adding the initProcessEnabled flag to your task definition.
• While starting SSM sessions outside of the execute-command action is possible, this results in the sessions not being logged and being counted against the session limit. We recommend limiting this access by denying the ssm:start-session action using an IAM policy. For more information, see Limiting access to the Start Session action.
• ECS Exec will use some CPU and memory. You’ll want to accommodate for that when specifying the CPU and memory resource allocations in your task definition.

Prerequisites for using ECS Exec

Before you start using ECS Exec, make sure you that you have completed these actions:

• Install and configure the AWS CLI. For more information, see AWS CLI.
• Install Session Manager plugin for the AWS CLI. For more information, see Install the Session Manager plugin for the AWS CLI.
• ECS Exec has version requirements depending on whether your tasks are hosted on Amazon EC2 or AWS Fargate:
  • 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. For more information, see Amazon ECS optimized AMIs.
  • If you’re using AWS Fargate, you must use platform version 1.4.0 or higher. For more information, see AWS Fargate platform versions.

Enabling and using ECS Exec

IAM permissions required for ECS Exec

The ECS Exec feature requires a task IAM role to grant containers the permissions needed for communication between the managed SSM agent (execute-command agent) and the SSM service. For more information, see Amazon ECS task IAM role. You should add the following permissions to a task IAM role and include the task IAM role in your task definition. For more information, see Adding and Removing IAM Policies.

Use the following policy for your task IAM role to add the required SSM permissions.

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

Enabling ECS Exec for your tasks and services

You can enable the ECS Exec feature for your services and standalone tasks by specifying the --enable-execute-command flag when using one of the following AWS CLI commands: create-service, update-service, start-task, or run-task.

For example, if you run the following command, the ECS Exec feature is enabled for a newly created service. For more information about creating services, see create-service.

aws ecs create-service \
    --cluster cluster-name \
    --task-definition task-definition-name \
    --enable-execute-command \
    --service-name service-name
    --desired-count 1

After you have enabled ECS Exec for a task, you can run the following command to confirm the task is ready to be used. If the lastStatus property of the ExecuteCommandAgent is listed as RUNNING and the enableExecuteCommand property is set to true, then your task is ready.

aws ecs describe-tasks \
    --cluster cluster-name \
    --tasks task-id

The following output snippet is an example of what you might see.

{
    "tasks": [
        {
            ...
            "containers": [
                {
                    ...
                    "managedAgents": [
                        {
                            "lastStartedAt": "2021-03-01T14:49:44.574000-06:00",
                            "name": "ExecuteCommandAgent",
                            "lastStatus": "RUNNING"
                        }
                    ]
                }
            ],
            ...
            "enableExecuteCommand": true,
            ...
        }
    ]
}

For more help read the article: ECS Exec for debugging

---

• 
• 
• 
•