AWS CDK CodeBuild Construct Library (v1)

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_codebuild'

  cause The `aws-cdk.aws-codebuild` package (for CDK v1) is not installed, or you might be trying to use v1 imports while having only `aws-cdk-lib` (CDK v2) installed.
  fix If using CDK v1, run `pip install aws-cdk.aws-codebuild`. If intending to use CDK v2, install `aws-cdk-lib` and update your imports to `from aws_cdk_lib import aws_codebuild`.

• AttributeError: module 'aws_cdk' has no attribute 'aws_codebuild'

  cause This error occurs when `aws-cdk-lib` (CDK v2) is installed, but the code attempts to use a v1 import path like `from aws_cdk import aws_codebuild`. In v2, all constructs are consolidated under `aws_cdk_lib`.
  fix If you are using CDK v2, change your import statement to `from aws_cdk_lib import aws_codebuild as codebuild`. If you intend to use v1, ensure only v1 packages are installed (`aws-cdk.core`, `aws-cdk.aws-codebuild`) and no v2 packages like `aws-cdk-lib`.

• CodeBuild project failed with exit code 1

  cause A generic build failure. Common culprits are misconfigured `BuildSpec`, insufficient IAM permissions for the CodeBuild service role, or issues with the source code or build environment.
  fix Inspect the detailed build logs in the AWS CodeBuild console for specific error messages. These logs will usually pinpoint the exact line in your `BuildSpec` that failed, or indicate a permissions issue (`AccessDenied`). Address the root cause based on log output.

Warnings

• breaking AWS CDK v1 (`aws-cdk.*` packages) and v2 (`aws-cdk-lib`) have fundamentally different import paths and API structures. Using v1 packages with v2 imports, or vice-versa, will lead to `ModuleNotFoundError` or `AttributeError`.
  Fix: For new projects, strongly consider using AWS CDK v2 (`pip install aws-cdk-lib`). For existing v1 projects, ensure `aws-cdk.core` and specific `aws-cdk.aws-*` packages are installed and use v1 import patterns. Refer to the official AWS CDK v2 upgrade guide for migration details.
• gotcha CodeBuild projects require an IAM service role with explicit permissions to access any AWS resources they interact with (e.g., S3 buckets for artifacts, ECR repositories for images, KMS keys, etc.). Missing permissions are a frequent cause of build failures.
  Fix: Review the CodeBuild logs carefully for access denied messages. Grant necessary IAM permissions to the `project.role` using methods like `project.role.add_to_policy()`, or define a custom `iam.Role` and assign it to the project. Always use `cdk diff` to inspect IAM policy changes before deploying.
• gotcha The `BuildSpec` configuration is sensitive to syntax and content. Incorrect YAML, invalid phase names, or commands referencing non-existent paths/executables will cause the build to fail.
  Fix: Validate your `BuildSpec` YAML syntax. Consult the official AWS CodeBuild User Guide for the correct `BuildSpec` schema and examples. Test complex `BuildSpec` files in a controlled environment or iterate quickly with small changes.

Install

• pip install aws-cdk.aws-codebuild==1.204.0 Install specific v1 version
• pip install "aws-cdk.aws-codebuild<2.0.0" Install latest v1 version

Imports

• Project
  wrong:

  from aws_cdk_lib import aws_codebuild as codebuild

  correct:

  from aws_cdk import aws_codebuild as codebuild

  This import path is specific to AWS CDK v1. AWS CDK v2 consolidates all constructs under `aws_cdk_lib`.
• Source
  wrong:

  from aws_cdk_lib import aws_codebuild

  correct:

  from aws_cdk import aws_codebuild as codebuild

  When using `aws-cdk.aws-codebuild` (v1), ensure your imports correctly reference `aws_cdk.aws_codebuild`.
• BuildSpec
  wrong:

  import aws_cdk.aws_codebuild

  correct:

  from aws_cdk import aws_codebuild as codebuild

  While direct import works, aliasing `aws_codebuild` as `codebuild` is a common convention for brevity and readability.

Quickstart

This quickstart demonstrates how to define a basic AWS CodeBuild project using AWS CDK v1. It creates a project with an inline build specification that prints a message during the build phase and uses `Source.no_source()` for simplicity. For deployment, ensure your AWS environment is configured (e.g., `aws configure`) and you have bootstrapped your CDK environment (`cdk bootstrap`). You can then run `cdk synth` to generate CloudFormation or `cdk deploy` to deploy it.

import os
from aws_cdk import (  # type: ignore
    core as cdk,
    aws_codebuild as codebuild
)

class MyCodeBuildStack(cdk.Stack):
    def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Define a simple CodeBuild project that prints a message
        codebuild.Project(
            self,
            "MySimpleBuildProject",
            project_name="MySimpleBuildProject",
            build_spec=codebuild.BuildSpec.from_object({
                "version": "0.2",
                "phases": {
                    "install": {
                        "commands": [
                            "echo 'Installing dependencies...'"
                        ]
                    },
                    "build": {
                        "commands": [
                            "echo 'Hello from CodeBuild!'",
                            "env"
                        ]
                    }
                },
                "artifacts": {
                    "files": []
                }
            }),
            source=codebuild.Source.no_source(), # No external source needed for this basic example
            environment=codebuild.BuildEnvironment(
                build_image=codebuild.LinuxBuildImage.STANDARD_5_0
            )
        )

app = cdk.App()
MyCodeBuildStack(app, "CodeBuildQuickstartStack")
app.synth()