Enabling Docker BuildKit in AWS CodeBuild: Performance, Security, and Secret Management

Enabling BuildKit in CodeBuild

To enable BuildKit, you must set the DOCKER_BUILDKIT environment variable or modify the Docker daemon configuration (/etc/docker/daemon.json). The environment variable approach is simpler and more commonly used in CodeBuild.

---

Steps to Enable BuildKit

1. Set the DOCKER_BUILDKIT Environment Variable: Add export DOCKER_BUILDKIT=1 to your buildspec.yml to enable BuildKit for your build commands.
2. Verify BuildKit and Docker Versions: Use docker buildx version and docker version to confirm BuildKit is active and compatible.
3. Optional: Enable BuildKit for Docker Compose: Set COMPOSE_DOCKER_CLI_BUILD=1 to ensure Docker Compose uses BuildKit for builds.

Below is a sample buildspec.yml configuration to enable and verify BuildKit:

version: 0.2
phases:
  pre_build:
    commands:
      - echo "Checking Docker and BuildKit versions"
      - docker version
      - docker buildx version || echo "BuildKit not found"
  build:
    commands:
      - export DOCKER_BUILDKIT=1
      - export COMPOSE_DOCKER_CLI_BUILD=1
      - echo "BuildKit enabled for the build phase"

Note:

• The COMPOSE_DOCKER_CLI_BUILD variable controls whether Docker Compose uses BuildKit. Set DOCKER_BUILDKIT=0 to revert to the classic builder.
• BuildKit fully supports building Linux containers. Windows container support is experimental and may have limitations. BuildKit is not supported on older CodeBuild images, including: aws/codebuild/standard:5.0, aws/codebuild/amazonlinux-x86_64-standard:4.0 and earlier versions.
• Use a newer CodeBuild image (e.g., aws/codebuild/standard:7.0) for BuildKit compatibility.

---

Use Case: Secure Secret Mounting with BuildKit in CodeBuild

BuildKit introduces secure secret handling, allowing you to mount secrets (e.g., API keys, certificates, passwords) during the build process without exposing them in the Dockerfile or image layers. When combined with AWS Systems Manager Parameter Store or Secrets Manager in CodeBuild, this ensures robust security for sensitive data.

Example: Mounting Secrets in a CodeBuild Project

The following lab setup demonstrates how to use BuildKit's secret mounting feature in a CodeBuild environment.

Buildspec Configuration (buildspec.yml)

version: 0.2
phases:
  pre_build:
    commands:
      - echo "Testing BuildKit secrets support"
      - docker version
      - docker buildx version || echo "BuildKit not found"
  build:
    commands:
      - export DOCKER_BUILDKIT=1
      - echo "mysecret" | docker build --secret id=mysecret,src=/dev/stdin -f Dockerfile

Explanation:

• The pre_build phase verifies the Docker and BuildKit versions.
• The build phase enables BuildKit with export DOCKER_BUILDKIT=1 and passes a secret (mysecret) via standard input to the docker build command.

Dockerfile (Dockerfile)

# syntax=docker/dockerfile:1
FROM alpine:latest
RUN --mount=type=secret,id=mysecret \
    cat /run/secrets/mysecret && \
    echo "Secret successfully mounted!"

Explanation:

• The # syntax=docker/dockerfile:1 directive ensures BuildKit is used.
• The --mount=type=secret,id=mysecret option mounts the secret at /run/secrets/mysecret during the build, accessible only for that RUN command.
• The secret is not stored in the final image, ensuring security.

---

Integration with AWS Secrets Manager or Parameter Store

To fetch secrets from AWS Systems Manager Parameter Store or Secrets Manager:

• Configure your CodeBuild project to access secrets via environment variables or IAM roles, as described in the AWS CodeBuild documentation.
• Pass the retrieved secret to the docker build command using --secret id=<secret-id>,src=<secret-value>

---

Troubleshooting

• BuildKit Not Found: If docker buildx version fails, ensure you're using a compatible CodeBuild image (e.g., aws/codebuild/standard:7.0 or later).
• Permission Issues: Verify that the CodeBuild IAM role has permissions to access Parameter Store or Secrets Manager if used.
• Secret Not Mounted: Ensure the --secret flag is correctly formatted and the secret ID matches the one used in the Dockerfile.

---

References

• Docker BuildKit Documentation
• Build Secrets in Docker BuildKit
• AWS CodeBuild Build Specification Reference