How to debug running CodeBuild builds in AWS Session Manager
Tags: aws, ssm, devops, codebuild
Published: 2023-07-10 09:44:56

{%- # TOC start (generated with https://github.com/derlin/bitdowntoc) -%}
- [Prerequisites](#prerequisites)
- [Pause the build](#pause-the-build)
- [Start the build](#start-the-build)
- [Connect to the build container](#connect-to-the-build-container)
- [Resume the build](#resume-the-build)
{%- # TOC end -%}

This is basically the [guide from AWS](https://docs.aws.amazon.com/codebuild/latest/userguide/session-manager.html) 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](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html). SSM Agent version must be 3.0.1295.0 or later.
2. Copy [this file](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/6.0/amazon-ssm-agent.json) 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:
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/q7frh8y8kcrxh2sbmbsn.png)
Click “Start build with overrides”:
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hduu6v9t91c2xqjnxjmk.png)
Click “Advanced build overrides”:
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6h2gokbylsinwkgqqypm.png)
By default, “AWS CodePipeline” will be chosen as Source provider, we’ll have to change it:
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/t0kxj93kkn8n1w5e3c3p.png)
It should look like this, where “Source version” is the name of your branch:
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cl6d5cvvs1n58uheqgms.png)
Also, check “Enable session connection” in "Environment" section:
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/glqhiw3cpjksobl9ougy.png)
## 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:
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/n0f1ovgayf4yjktzlrdx.png)
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2y0r6yb35y0m7kzu4dtv.png)
## Resume the build
After you finish examining the build container, issue the `codebuild-resume` command from the container shell:
![AWS CodeBuild](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1unww0174k14vd7jas5k.png)