AWS Toolkit for JetBrains
User Guide

Debugging Code in an Amazon Elastic Container Service Cluster by Using the AWS Toolkit for JetBrains

You can use the AWS Toolkit for JetBrains to debug code in an Amazon Elastic Container Service (Amazon ECS) cluster in an AWS account.

Note

Debugging code in Amazon ECS clusters is currently in beta.

Do not use this feature in a production environment. Debugging code in an Amazon ECS cluster changes the state of resources in your AWS account including, but not limited to, stopping associated Amazon ECS services and changing their configurations. Also, manually changing the state of resources while code debugging is enabled could lead to unpredictable results.

Prerequisites

Before you begin debugging your code, you must have the following:

  1. The Docker image that you want to use to debug your code. This image can be hosted in either of the following:

    Note

    If you don't already have an image available, we recommend one of the following:

  2. In your AWS account, an AWS Identity and Access Management (IAM) role with AWS permissions that are needed by the code you want to debug. This role will be used as the task role by Amazon Elastic Container Service (Amazon ECS). This task role must also have a trust relationship with the ecs-tasks.amazonaws.com service principal and must contain a reference to the AmazonSSMManagedInstanceCore AWS managed policy. For more information, see how to set up the Amazon ECS task role.

  3. In your AWS account, an Amazon ECS cluster that contains the service you want to debug. This service must use the AWS Fargate launch type and have at least one task definition also based on Fargate. For more information, see how to set up the Amazon ECS cluster.

  4. In your AWS account, a specific IAM customer managed policy that you add to the appropriate IAM entity (such as an IAM user, group, or role) that is associated with AWS credentials you specify when connecting to the AWS Toolkit for JetBrains. For more information, see how to add the IAM customer managed policy to the IAM entity.

  5. On your local development machine, a copy of the code you want to debug.

Debugging Code

After you complete the preceding prerequisites, you can debug your code as follows:

  1. Open AWS Explorer, if it isn't already open. If the Amazon ECS cluster is in an AWS Region that's different from the current one, switch to a different AWS Region that contains it.

  2. Expand ECS, and then expand Clusters.

  3. Expand your Amazon ECS cluster, right-click your service, and then choose Enable Cloud Debugging. For example, in the following screen shot, the cluster is named java, and the service is named java-service.

    
        Enabling cloud debugging in the AWS Explorer
  4. When prompted, choose your Amazon ECS task role, and then choose OK.

  5. The status bar displays the message Configuring Cloud Debugging resource. Wait until the Build Output tab of the Build tool window displays a successful configuration message. (A related pop-up also displays in the bottom right corner.) This will take several minutes.

    Note

    As you enable code debugging in your AWS account for the first time, the AWS Toolkit for JetBrains creates an Amazon S3 bucket in your AWS account. The bucket's name follows the format of do-not-delete-cloud-debug-Region-ID-account-ID. The JetBrains Toolkit stores information in this bucket to enable code debugging. Do not delete this bucket or modify its contents. If you do, code debugging might stop working or produce unexpected results. If you accidentally delete or modify this bucket, the JetBrains Toolkit will try to recreate the bucket. You can also force the JetBrains Toolkit to recreate the bucket by choosing Enable Cloud Debugging again as described earlier or by choosing Disable Cloud Debugging as described later in this procedure.

  6. With the code you want to debug displayed, in the AWS Explorer, expand ECS, expand Clusters, and then expand your cluster. A service displays with a debug icon next to it. This indicates the service is now enabled for cloud debugging. Right-click the service with the debug icon, and then choose Debug.

    
        Debugging an Amazon ECS service in the AWS Explorer
  7. Complete the Edit configuration dialog box, and then choose Debug.

    Note

    To make any changes later to this configuration, on the menu bar, choose Run, Edit Configurations. Then expand Amazon ECS Service Cloud Debug, and choose the service's name.

  8. Use the IDE's built-in debugging tools to debug your code as usual.

  9. If you make any changes to your code, you can start debugging again: in the AWS Explorer, expand ECS, expand Clusters, and then expand your cluster. Right-click your service with the debug icon next to it, and then choose Debug.

  10. If you make any changes to the associated Dockerfile, you must rebuild and republish the Docker image, and then repeat this procedure from the beginning.

  11. To disable debugging, in the AWS Explorer, expand ECS, expand Clusters, and then expand your cluster. Right-click your service with the debug icon next to it, and then choose Disable Cloud Debugging. A pop-up displays, confirming that debugging is disabled.

Setting Up the Amazon ECS Task Role

Note that the following information applies to permissions that Amazon ECS needs, which is different from permissions that the AWS Toolkit for JetBrains needs.

To debug code in Amazon Elastic Container Service (Amazon ECS) clusters, you must first have in your AWS account an AWS Identity and Access Management (IAM) role with AWS permissions that are needed by the code you want to debug. This role will be used as the task role by Amazon Elastic Container Service (Amazon ECS). This task role must also have a trust relationship with the ecs-tasks.amazonaws.com service principal and must contain a reference to the AmazonSSMManagedInstanceCore AWS managed policy.

To create a role that meets these requirements, see Creating a Role for an AWS Service (Console) in the IAM User Guide, specifying the following settings:

  1. For Choose the service that will use this role, choose Elastic Container Service.

  2. For Select your use case, choose Elastic Container Service Task.

  3. For Attach permissions policies, choose AmazonSSMManagedInstanceCore.

To add additional AWS permissions to an existing Amazon ECS task role, see "To change the permissions allowed by a role (console)" in Modifying a Role (Console) in the IAM User Guide.

Setting Up the Amazon ECS Cluster

To debug code in Amazon Elastic Container Service (Amazon ECS) clusters, you must first have in your AWS account an Amazon ECS cluster that contains the service you want to debug. This service must use the AWS Fargate launch type and have at least one task definition also based on Fargate.

To quickly create a Fargate cluster, service, and task definition that meets the minimum requirements, see Getting Started with Amazon ECS using Fargate in the Amazon Elastic Container Service User Guide for AWS Fargate. The only required settings are in Step 1: Container and Task. Specifically, after you specify a name for the container, for Container definition, choose Configure. Then specify an Image that is compatible with the code you want to debug.

Note

If you don't already have an image available, we recommend one of the following:

For advanced scenarios, you can create a Fargate cluster, task definition, and service independently. To do so, see the following in the Amazon Elastic Container Service Developer Guide:

Adding the IAM Customer Managed Policy

Note that the following information applies to permissions that the AWS Toolkit for JetBrains needs, which is different from permissions that Amazon ECS needs.

When setting up to debug code in Amazon ECS clusters, we strongly recommend that you follow the AWS security best practice of granting least privilege. Granting least privilege means granting only the permissions required to perform a task. To grant least privilege for debugging code in Amazon ECS clusters, you must attach a specific IAM customer managed policy as follows to an IAM entity (such as an IAM user, group, or role). This IAM entity must be associated with the credentials that you specify when you connect to the AWS Toolkit for JetBrains.

In the following policy statement, permission is granted to two Amazon ECS services named MyService and MyOtherService as well as to two Amazon ECS task roles named MyTaskRole and MyOtherTaskRole. Change the names of these example services and task roles to match your own, and then attach this policy to the appropriate IAM entity.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowedECSServices", "Effect": "Allow", "Action": [ "ecs:UpdateService" ], "Resource": [ "arn:aws:ecs:*:*:service/*/MyService", "arn:aws:ecs:*:*:service/*/MyOtherService" ] }, { "Sid": "AllowedIAMRoles", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::*:role/MyTaskRole", "arn:aws:iam::*:role/MyOtherRole" ], "Condition": { "StringEquals": { "iam:PassedToService": "ecs-tasks.amazonaws.com" } } }, { "Effect": "Allow", "Action": [ "s3:CreateBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket" ], "Resource": "arn:aws:s3:::do-not-delete-cloud-debug-*" }, { "Effect": "Allow", "Action": [ "ecs:ListServices", "ecs:DescribeServices", "ecs:ListTasks", "ecs:DescribeTasks", "ecs:DescribeTaskDefinition", "elasticloadbalancing:DescribeListeners", "elasticloadbalancing:DescribeRules", "elasticloadbalancing:DescribeTargetGroups", "ecr:GetAuthorizationToken", "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream" ], "Resource": [ "arn:aws:logs:*:*:cloud-debug*" ] }, { "Effect": "Allow", "Action": [ "ecs:CreateService", "ecs:DeleteService" ], "Resource": "arn:aws:ecs:*:*:service/*/cloud-debug*" }, { "Effect": "Allow", "Action": [ "ecs:RegisterTaskDefinition" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "elasticloadbalancing:ModifyListener", "elasticloadbalancing:ModifyRule", "elasticloadbalancing:ModifyTargetGroupAttributes" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "elasticloadbalancing:CreateTargetGroup", "elasticloadbalancing:DeleteTargetGroup" ], "Resource": "arn:aws:elasticloadbalancing:*:*:targetgroup/cloud-debug*" }, { "Effect": "Allow", "Action": [ "ssm:StartSession", "ssm:TerminateSession", "ssm:ResumeSession", "ssm:DescribeSessions", "ssm:GetConnectionStatus" ], "Resource": [ "*" ] }, { "Effect": "Allow", "Action": [ "application-autoscaling:RegisterScalableTarget", "application-autoscaling:DeregisterScalableTarget", "application-autoscaling:DescribeScalableTargets" ], "Resource": "*" } ] }

You can use tools such as the IAM console within the AWS Management Console to create an IAM customer managed policy and then add the policy to the appropriate IAM entity (such as an IAM user, group, or role).