How to Access the Containers on AWS Fargate Cluster

We have lots of containerised applications running on AWS Fargate Cluster and recently, more and more requirements from our dev team jumped out and they would like to access the containers directly for trouble shooting purpose.

AWS Fargate is a serverless compute engine for containers and you can just deploy your containerised application without managing the servers. However, without servers, you cannot just easily run docker exec -it to access the container. You need AWS Session Manager’s help to build a channel for you. See below diagram.

Workflow Diagram

From configuration perspective, you need to have AWS CLI v2 and session-manager-plugin installed on your machine. You also need to give the ecs:ExecuteCommand permission to your IAM role (if you use EC2 as a bastion host) or IAM user (if you configure AWS credential). Lastly, you need to give SSM permission to the Task Role.

Let’s go through the procedure step by step:

I assume you have got existing service/tasks running on Fargate.

1. Install AWS Cli v2, please follow the AWS document.
2. Install the session-manager-plugin, please follow this.
3. Update the task role with below permissions. Please read this to understand what these actions are

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

1. Update the IAM role or IAM user for your connecting machine. If you have Administrator with Allow *, you can skip this step. See below permission.

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

The policy above only gives you ExecuteCommand permission which you can associate it to your dev team user or group. But for updating the service with — enable-execute-command as an admin, I would suggest you can use below policy for an admin user to manage the ECS/Fargate Cluster.

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

1. (Optional) Check the task if executeCommand is enabled or not.

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

1. Enable ECS executeCommand

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

If you have forceNewDeployment enabled, you just need to wait the new task is up. If you want it urgently and the container is not a critical one, you can stop the task manually and the new task will be created.

1. Verify if executeCommand is enabled. The task-id will be changed.

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

1. Log in to the container.

aws ecs execute-command --cluster <cluster-name> --task <task-id> --container <container-name> --interactive --command "/bin/sh"

Best Practice

Honestly, I would not recommend to access the Fargate container especially for production environment. Our team is also build a very practical way for developers to trouble shoot on their local environment.

We have been using Docker Compose to build the local dev environment for quite a long time and it is running perfectly for trouble shooting.

Hope this is helpful! If you have any questions about this, feel free to leave your comments.

Harry in NZ