How to debug running CodeBuild builds in AWS Session Manager

• Prerequisites
• Pause the build
• Start the build
• Connect to the build container
• Resume the build

This is basically the guide from AWS with added screenshots of the process

Note
This feature is not available in Windows environments.

Prerequisites

To allow Session Manager to be used with the build session, you must enable session connection for the build. There are two prerequisites:

• CodeBuild Linux standard curated images already have the SSM agent installed and the SSM agent ContainerMode enabled.

If you are using a custom image for your build, do the following:

1. Install SSM Agent. For more information, see this guide. SSM Agent version must be 3.0.1295.0 or later.
2. Copy this file to the /etc/amazon/ssm/ directory in your image. This enables Container Mode in the SSM agent.

Note
Custom images would require most updated SSM agent for this feature to work as expected.

• The CodeBuild service role must have the following SSM policy:

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

You can have the CodeBuild console automatically attach this policy to your service role when you start the build. Alternatively, you can attach this policy to your service role manually.

• If you have Auditing and logging session activity enabled in Systems Manager preferences, the CodeBuild service role must also have additional permissions. The permissions are different, depending on where the logs are stored.

CloudWatch Logs

• If using CloudWatch Logs to store your logs, add the following permission to the CodeBuild service role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "logs:DescribeLogGroups",
      "Resource": "arn:aws:logs:<region-id>:<account-id>:log-group:*:*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:<region-id>:<account-id>:log-group:<log-group-name>:*"
    }
  ]
}

Amazon S3

• If using Amazon S3 to store your logs, add the following permission to the CodeBuild service role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetEncryptionConfiguration",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket-name>",
        "arn:aws:s3:::<bucket-name>/*"
      ]
    }
  ]
}

For more information, see Auditing and logging session activity in the AWS Systems Manager User Guide.

Pause the build

To pause the build, insert the codebuild-breakpoint command in any of the build phases in your buildspec file. The build will be paused at this point, which allows you to connect to the build container and view the container in its current state.
For example, add the following to the build phases in your buildspec file:

phases:
  pre_build:
    commands:
      - echo Entered the pre_build phase...
      - echo "Hello World" > /tmp/hello-world
      - codebuild-breakpoint

Start the build

Go to your project’s pipeline, and click on “AWS CodeBuild” link in "Build" stage. This will take you to CodeBuild project, corresponding to your pipeline:

Click “Start build with overrides”:

Click “Advanced build overrides”:

By default, “AWS CodePipeline” will be chosen as Source provider, we’ll have to change it:

It should look like this, where “Source version” is the name of your branch:

Also, check “Enable session connection” in "Environment" section:

Connect to the build container

After all of this, you can scroll to the bottom and click "Start Build". After some time, link to connect to the build container will appear. Click it and a terminal session will open that allows you to browse and control the build container:

Resume the build

After you finish examining the build container, issue the codebuild-resume command from the container shell: