Following an "AWS Unless" strategy within our company, it was only a matter of time before we would move our builds to AWS CodeBuild and AWS CodePipeline. Migrating our legacy pipelines to AWS CodeBuild turned out to be a pretty straightforward job. For that reason, CodeBuild was easily adopted by our development teams.
However, in general there was one complaint about CodeBuild, troubleshooting problems in the buildspec.yml
was hard, mainly because access to the remote session was nonexistent.
That was until last July when AWS Session Manager access for AWS CodeBuild was announced. It's strange but it seems that the release of this awesome feature went by unnoticed!? Maybe that's due to the fact that the press release seems to miss the right semantics? It's definitely a hard post to find even for Google if you don't use the right words. Fingers crossed that this article can bring more attention to this feature :-)
By enabling remote access, AWS Session Manager finally brings debug capabilities to AWS CodeBuild. Besides Session Manager access, the new CodeBuild command codebuild-breakpoint
is the key to this new feature.
In Practice
-
Add the permission to use AWS Session manager to AWS CodeBuild:
CodeBuildServiceRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Statement: - Effect: Allow Principal: Service: - codebuild.amazonaws.com Action: - sts:AssumeRole Path: / Policies: - PolicyName: log-access PolicyDocument: Statement: - Effect: Allow Action: - logs:CreateLogStream - logs:PutLogEvents - logs:CreateLogGroup Resource: - !Sub arn:aws:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/codebuild/* - PolicyName: ssm-access PolicyDocument: Statement: - Effect: Allow Action: - ssmmessages:CreateControlChannel - ssmmessages:CreateDataChannel - ssmmessages:OpenControlChannel - ssmmessages:OpenDataChannel Resource: "*" ...
-
Add a breakpoint to your
buildspec.yml
build: commands: - ... - codebuild-breakpoint - ...
-
Start a build for debugging
- Start a build using "Advanced Build Overrides"
- Under advanced settings choose "Enable Session Connection"
- Start a build using "Advanced Build Overrides"
Start a remote session using the Web Console
Start a remote session using the CLI
- Grab the Build ID (aka Build Run)
-
Get the
sessionTarget
using the Build Id
aws codebuild batch-get-builds --ids <buildID> --region <region>
IMHO, currently, the documentation for
batch-get-builds
falls short. Getting thesessionTarget
using the CLI could be tricky if you don't use the right settings or if you're not using a recent version of the CLI. Therefore I made a Pull Request to change the documentation to:Copy the
sessionTarget
property value. Note:sessionTarget
is only available if output isjson
ortable
. If output is set totext
look forDEBUGSESSION
instead. If the property is missing from the output then update your CLI to a more recent version. -
Once you have copied the
sessionTarget
value you can start a new remote session using:
aws ssm start-session --target <sessionTarget> --region <region>
Debug your build :-)
You're all set. To stop a debug session just execute $ codebuild-resume
.
Until next time!
Discussion