View a running build in Session Manager
In Amazon CodeBuild, you can pause a running build and then use Amazon Systems Manager Session Manager to connect to the build container and view the state of the container.
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:
-
Install the SSM Agent. For more information, see Manually install SSM Agent on EC2 instances for Linux in the Amazon Systems Manager User Guide. The SSM Agent version must be 3.0.1295.0 or later.
-
Copy the file https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.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 Amazon 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
This code creates the /tmp/hello-world
file and then pauses the
build at this point.
Start the build
To allow Session Manager to be used with the build session, you must enable session connections for the build. To do this, when starting the build, follow these steps:
Open the Amazon CodeBuild console at https://console.amazonaws.cn/codesuite/codebuild/home
. -
In the navigation pane, choose Build projects. Choose the build project, and then choose Start build with overrides.
-
Choose Advanced build overrides.
-
In the Environment section, choose the Enable session connection option. If this option is not selected, all of the codebuild-breakpoint and codebuild-resume commands are ignored.
-
Make any other desired changes, and choose Start build.
-
Monitor the build status in the console. When the session is available, the Amazon Session Manager link appears in the Build status section.
Connect to the build container
You can connect to the build container in one of two ways:
- CodeBuild console
-
In a web browser, open the Amazon Session Manager link to connect to the build container. A terminal session opens that allows you to browse and control the build container.
- Amazon CLI
-
Note
Your local machine must have the Session Manager plugin installed for this procedure. For more information, see Install the Session Manager Plugin for the Amazon CLI in the Amazon Systems Manager User Guide.
-
Call the batch-get-builds api with the build ID to get information about the build, including the session target identifier. The session target identifier property name varies depending on the output type of the
aws
command. This is why--output json
is added to the command.aws codebuild batch-get-builds --ids
<buildID>
--region<region>
--output json -
Copy the
sessionTarget
property value. ThesessionTarget
property name can vary depending on the output type of theaws
command. This is why--output json
is added to the command in the previous step. -
Use the following command to connect to the build container.
aws ssm start-session --target
<sessionTarget>
--region<region>
-
For this example, verify that the /tmp/hello-world
file exists
and contains the text Hello World
.
Resume the build
After you finish examining the build container, issue the codebuild-resume command from the container shell.
$
codebuild-resume