DEV Community

Cover image for How-to debug and trace problems in AWS CodeBuild
Gert Leenders
Gert Leenders

Posted on • Updated on • Originally published at element7.io

How-to debug and trace problems in AWS CodeBuild

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 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.

  build:
    commands:
      - ...
      - codebuild-breakpoint
      - ...
Enter fullscreen mode Exit fullscreen mode

Debug AWS CodeBuild Using the AWS Web Console

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

Build with overrides

Pick Advanced build overrides.

Advanced overrides

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

Allow SSM

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

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

Debug AWS CodeBuild Using the CLI

Prerequisites

First, verify your CodeBuild Service role includes the following permissions

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

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

The CLI commands

Start a new build and print its Build identifier

 aws codebuild start-build --project-name <ProjectName> --debug-session-enabled --output json | jq '.build.id'
Enter fullscreen mode Exit fullscreen mode

Next, get the sessionTarget using the Build identifier

 aws codebuild batch-get-builds --ids <BuildID> --output json | jq '.builds[0].debugSession.sessionTarget'
Enter fullscreen mode Exit fullscreen mode

Finally, use the sessionTarget to start a new remote session

aws ssm start-session --target <sessionTarget> --region <region>
Enter fullscreen mode Exit fullscreen mode

Now, you enter your remote build using Session Manager

SSM CLI

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

That's all you need to know πŸ˜‰

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

Enjoy and until next time!

Top comments (1)

Collapse
 
andrewbrown profile image
Andrew Brown πŸ‡¨πŸ‡¦

I'm blown away by this feature. I'm currently starting at failing build runs and I'm lucky enough to see you found this obscure but very useful feature.