Amazon ECS (Elastic Container Service) Fargate is a powerful service that allows you to run containers without managing the underlying infrastructure. While Fargate offers numerous benefits in terms of scalability and ease of use, it can sometimes be challenging to interact with containers running within Fargate. AWS Systems Manager Session Manager, combined with ECS Exec, offers a secure and efficient solution for interactively accessing and managing Fargate containers without compromising security or requiring direct SSH access. This guide will walk you through the steps to enable and use ECS Exec with AWS Systems Manager Session Manager to access ECS Fargate containers interactively.

How does ECS Exec function ?

ECS Exec operates by utilizing AWS Systems Manager Session Manager to create and manage secure communication channels between your local machine and the containers running within Amazon ECS Fargate tasks. This architecture ensures a secure, isolated, and interactive experience for debugging and troubleshooting containerized applications.

Prerequisites

For Amazon ECS Exec to work properly, you need to ensure that you meet several prerequisites to set up the necessary environment and permissions. Here’s a list of prerequisites to ensure ECS Exec works as intended:

1. ECS Cluster and Fargate Tasks
   Have an active Amazon ECS cluster running Fargate tasks with the ECS agent version that supports ECS Exec. The ECS agent must be at least version 1.47.0.

2. IAM Roles and Policies
   The ECS task role used by your Fargate tasks needs to have appropriate permissions to interact with AWS Systems Manager Session Manager.

3. Session manager plugin for AWS CLI
   The session manager plugin is an extension for your AWS CLI that facilitates connecting to EC2 instances or AWS Fargate tasks.

4. Network Configuration

   • ECS tasks must be deployed within a Virtual Private Cloud (VPC).
   • Ensure that the necessary networking configurations, such as subnets, security groups, and routes, are properly set up to enable communication between ECS Fargate tasks and Systems Manager.

Enabling network communication between ECS Fargate Task and System Manager

Establishing network connectivity between an ECS Fargate task and AWS Systems Manager requires configuring essential networking elements to guarantee seamless communication between these services.

Fargate Task Networking

In Amazon ECS for AWS Fargate, tasks need to use the “awsvpc” network mode, which grants each task its own elastic network interface.If you choose to use this network mode when launching a task or setting up a service, you need to mention which subnets to connect the network interface to and which security groups to use for the network interface.

1.) Fargate tasks placed in public subnets: The task’s elastic network interface should have a public IP address, and there should be a route either directly to the internet or through a NAT gateway that can send internet requests.In this scenario, the Fargate task can readily interact with the AWS Systems Manager service using the public internet.

2.) Fargate tasks placed in private subnets: For a Fargate task in a private subnet and needs to connect with the AWS Systems Manager (SSM) service,it requires either a NAT gateway within the subnet to route requests to the internet or Interface VPC Endpoints specifically configured for the AWS ssm, ec2Messages and ssmmessages services.

Choosing a VPC endpoint offers an array of benefits, including heightened security, privacy, compliance adherence, improved network performance, and enhanced control over data transmission. These factors make it a preferable option over relying on public internet connectivity for interacting with AWS services like AWS Systems Manager.

Setting up ECS Exec for Fargate Tasks

Step 1: Installing Session Manager Plugin for AWS Cli

To install the Session Manager plugin, refer to the AWS documentation and follow the instructions tailored to your client’s operating system.

The following example shows the installation process of the Session Manager plugin on a Mac OS;

Step 2: Include SSM Permissions for SSM in the ECS Task IAM Role

Attach a policy to ECS Task IAM role that grants permissions for ECS Exec, such as the following example policy:

{
  "Effect": "Allow",
  "Action": [
    "ssmmessages:CreateControlChannel",
    "ssmmessages:CreateDataChannel",
    "ssmmessages:OpenControlChannel",
    "ssmmessages:OpenDataChannel"
  ],
  "Resource": "*"
}

Step 3: Incorporate ECS ExecuteCommand permissions into your IAM Role

Make sure that you’ve added the necessary ECS ExecuteCommand permission to your IAM role. Add a policy that grants ECS ExecuteCommand permission. Here’s an example policy:

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

Step 4: Activate ECS Exec for your services

i.) List the clusters

aws ecs list-clusters --profile profile1

This command will return a list of ECS cluster ARNs (Amazon Resource Names) associated with the specified AWS CLI profile, “profile1”. Make sure you have the necessary credentials and permissions configured in “profile1” to access the ECS service.

ii.) List the Task Definitions

aws ecs list-task-definitions --profile profil

By executing this command, you’ll receive a list of ARNs (Amazon Resource Names) representing the available ECS task definitions in the “profile1” AWS CLI profile.

iii.) List the services within TestCluster

aws ecs list-services --cluster TestCluster  --profile profile1

By executing this command, you’ll receive a list of ARNs (Amazon Resource Names) representing the services associated with the “TestCluster” ECS cluster in the “profile1” AWS CLI profile.

iv) Enable ECS Exec

Enable ECS Exec for an exisiting ECS Service

aws --profile profile1 ecs update-service \
--cluster TestCluster \
--service TestServic2 \
--enable-execute-command \
--force-new-deployment

By running this command, you’re enabling the ECS Exec feature for the specified service and ensuring a new deployment of tasks within the service. This ensures that ECS Exec is effectively integrated into the updated tasks.

Enable ECS Exec for a new ECS Service

aws ecs create-service --cluster TestCluster \
--service-name TestService3 \
--task-definition TestTaskDef:3 \ 
--desired-count 1 \ 
--network-configuration "{\"awsvpcConfiguration\":{\"subnets\":[\"subnet-0b642d3591fe3cf87\"],\"assignPublicIp\":\"ENABLED\"}}" \
--launch-type FARGATE \
--enable-execute-command \
--profile profile1

By executing this command, you’re creating a new ECS service that deploys the specified criteria, including enabling the ECS Exec feature and configuring the network settings (Deploy the Fargate task in a public subnet and activate automatic assignment of public IP addresses for the NICs) for Fargate tasks.

Step 5: Accessing the Container using ECS exec

Upon completing all the aforementioned steps, you will now observe the existence of the following two services running within the cluster.

Let’s proceed to attempt accessing TestService3 using AWS Systems Manager (SSM).

Choose TestService3, navigate to the Tasks tab, and make a note of the Task ID(cf0be9da96e54446984217c9921435ec) and Container Name (TestContainer). Afterward, execute the following command;

aws --profile profile1 ecs execute-command --cluster TestCluster \
--task cf0be9da96e54446984217c9921435ec \                                                                                                         
--container TestContainer \
--command "/bin/sh" \     
--interactive

By running this command, you’re utilizing the “profile1” profile to trigger the execution of the specified command within the ECS task, providing an interactive shell interface for interaction.

Congratulations! You’ve successfully remotely accessed the running container, powered by Fargate. This remote access allows you to troubleshoot any errors with remarkable ease.

How do I troubleshoot errors I receive when performing Amazon ECS Exec on my Fargate tasks?

Conclusion

Amazon ECS Fargate, coupled with AWS Systems Manager Session Manager and ECS Exec, empowers developers and operators to dynamically troubleshoot and manage containers securely. By following this guide, you can efficiently access and interact with Fargate containers, streamline debugging, and ensure the operational success of your containerized applications.