ECS Exec Usage Guide

To begin using ECS Exec, follow these steps to verify and enable the necessary configurations.

Prerequisites: AWS CLI and Session Manager Plugin Installation

Before using ECS Exec, ensure that you have the following installed on your local machine:

1. AWS CLI:
   • To install the AWS CLI, follow the official instructions for your operating system: AWS CLI Installation Guide

After installation, verify it by running:

   aws --version

1. Session Manager Plugin: The ECS Exec feature requires the Session Manager Plugin for the AWS CLI. To install it, follow the steps for your operating system:

• Windows:
  

   msiexec.exe /i https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPluginSetup.exe
  

• macOS:
  

   curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac/sessionmanager-bundle.zip" -o "sessionmanager-bundle.zip"
   unzip sessionmanager-bundle.zip
   sudo ./sessionmanager-bundle/install
  

• Linux:
  

   curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_amd64/session-manager-plugin.rpm" -o "session-manager-plugin.rpm"
   sudo yum install -y session-manager-plugin.rpm
  

After installation, verify it by running:

   session-manager-plugin --version

1. Verify Your Task Configuration:

First, ensure that the task you want to connect to has the enableExecuteCommand option enabled. Use the following command to describe the task:

aws ecs describe-tasks \
    --cluster <cluster-name> \
    --region <region-id> \
    --tasks <task-id>

Check the output to ensure the enableExecuteCommand flag is set to true:

"enableExecuteCommand": true

2. Verify Service Configuration (If Applicable):

If your task is part of a service, verify that the service also has the enableExecuteCommand option enabled by running the following command:

aws ecs describe-services \
    --cluster <cluster-name> \
    --services <service-name>

Check for the enableExecuteCommand flag in the output:

"enableExecuteCommand": true

3. Enabling enableExecuteCommand:

If the enableExecuteCommand flag is false, follow these steps to enable it.

For One-Time Run Tasks:

You can enable ECS Exec when you run the task by adding the --enable-execute-command flag in the run-task command:

aws ecs run-task \
    --cluster <cluster-name> \
    --task-definition <taskdef-name> \
    --network-configuration awsvpcConfiguration="{subnets=[$PUBLIC_SUBNET1, $PUBLIC_SUBNET2],securityGroups=[$ECS_EXEC_DEMO_SG_ID],assignPublicIp=DISABLED}" \
    --enable-execute-command \
    --launch-type FARGATE \
    --tags key=environment,value=production \
    --region $AWS_REGION

For Services:

Currently, you cannot enable ECS Exec for services through the AWS Management Console (GUI). Instead, you need to update the service using the following CLI command:

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

4. ECS Fargate and SSM Agent:

ECS Fargate uses the SSM Agent to allow direct access to containers via Session Manager. Therefore, ensure that your task definition includes a task role, and that the task role has the appropriate IAM policy. To facilitate testing, you can temporarily attach the AdministratorAccess policy (though this is only recommended for testing purposes).

5. Executing Commands in Containers:

Once everything is configured, you can execute commands within your containers. Use the following commands based on the operating system of your container.

For Windows Containers:

aws ecs execute-command  \
    --region $AWS_REGION \
    --cluster <cluster-name>  \
    --task <task-id> \
    --container <container-name> \
    --command "powershell.exe" \
    --interactive

For Linux Containers:

aws ecs execute-command  \
    --region $AWS_REGION \
    --cluster <cluster-name>  \
    --task <task-id> \
    --container <container-name> \
    --command "/bin/bash" \
    --interactive

With the addition of these prerequisites, your documentation will help users set up everything they need to use ECS Exec smoothly. Let me know if you need any further adjustments!