How-to debug and trace problems in AWS CodeBuild
Tags: aws, devops, beginners
Published: 2020-11-22 13:43:35


_Update 2022-11-18: multiple tweaks keeping this post up-to-date_

For ease, conformity, and security reasons, it makes sense to host your infrastructure on a single ecosystem as much as possible. Therefore, I prefer to use AWS CodePipeline and AWS CodeBuild as CI/CD solutions when developing on AWS.

Both AWS CodeBuild and AWS CodePipeline do a very decent job; however, I always found troubleshooting CodeBuild `buildspec.yml` files difficult and tedious, mainly because access to the remote CodeBuild session was nonexistent. Well, that was until [AWS Session Manager access for AWS CodeBuild](https://aws.amazon.com/about-aws/whats-new/2020/07/aws-codebuild-now-supports-accessing-build-environments-with-aws-session-manager/) was announced.

I'm still trying to figure out why, but this great feature's release went unnoticed!? Even today, when people ask me questions about failing AWS CodeBuild builds, I need to bring this feature to their attention.

**Let’s take a closer look at how this looks in practice.**

## Exploring AWS CodeBuild Debugging

Enabling remote access on AWS CodeBuild, AWS Session Manager brings debug capabilities to your `buildspec` files. Besides Session Manager access, the CodeBuild command `codebuild-breakpoint` is the key to this feature.

No matter if you'll use the Web console or CLI, first of all, add a breakpoint to your `buildspec.yml` file.

```console
  build:
    commands:
      - ...
      - codebuild-breakpoint
      - ...
```

### Debug AWS CodeBuild Using the AWS Web Console

Start a new build with debugging capabilities using `Start build with overrides`.

![Build with overrides](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dpkco4ah2awwk12gl8gt.png)

Pick `Advanced build overrides`.

![Advanced overrides](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/d2ux6v7polh30cq7z9ik.png)

Under `Environment`, tick `Enable session Connection` and allow CodeBuild to modify the service role.

![Allow SSM](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yllght908d8nuj8uksjv.png)

Start the build. Once the build runs, you must select the running build in the `Build History`. Under `Build Status` you'll find the option to log in to your remote build using Session Manager.

![Session Manager](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/g5x8njvl903hw9kzn5wm.png)

If you click the link, a remote session to your build environment will open. Go ahead and troubleshoot your buildspec in the remote session. When ready, enter `codebuild-resume` to continue your build. It's also safe to
terminate the remote session now.

![Resume](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bx5jjk2s1yfjl48usarc.png)

### Debug AWS CodeBuild Using the CLI

#### Prerequisites

First, verify your CodeBuild Service role includes the following permissions

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

Next, ensure you have the following tools installed before running the CLI commands

- [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-version.html)
- [the Session Manager plugin for the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
- [jq](https://stedolan.github.io/jq/)

### The CLI commands

Start a new build and print its `Build identifier`

```console
 aws codebuild start-build --project-name <ProjectName> --debug-session-enabled --output json | jq '.build.id'
```

Next, get the `sessionTarget` using the `Build identifier`

```console
 aws codebuild batch-get-builds --ids <BuildID> --output json | jq '.builds[0].debugSession.sessionTarget'
```

Finally, use the `sessionTarget` to start a new remote session

```console
aws ssm start-session --target <sessionTarget> --region <region>
```

Now, you enter your remote build using Session Manager

![SSM CLI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/awpwydo0vwutpq5xln0l.png)

To stop a debug session execute `codebuild-resume` and `exit` your session.

That's all you need to know :wink:

_Remark: if using Amazon S3 to store your logs ensure to adjust your CodeBuild Service role accordingly. In case that policy is missing you get an SSM Session with a stuck prompt without further feedback. So, if using S3 to store your logs, ensure to have that policy right._

Reference: [View a running build in Session Manager](https://docs.aws.amazon.com/codebuild/latest/userguide/session-manager.html)

Enjoy and until next time!