CodeBuild

Introduction

AWS CodeBuild is a managed AWS service for the build and testing phases of software development. CodeBuild allows you to define your build project, set the source code location, and handles the building and testing, while supporting various programming languages, build tools, and runtime environments. LocalStack supports CodeBuild out of the box and can be easily integrated into your pipeline to run your tests against a cloud emulator.

Note

LocalStack depends on the Docker socket to emulate your infrastructure. To enable it, update your project by ticking Environment > Additional Configuration > Privileged > Enable this flag if you want to build Docker Images or want your builds to get elevated privileges.

Snippets

CodeBuild has the capability to use LocalStack’s GitHub Action.

Start up LocalStack

Native Runner

version: 0.2
...
phases:
  pre_build:
    commands:
      - pip3 install localstack awscli
      - docker pull public.ecr.aws/localstack/localstack:latest
      - localstack start -d
      - localstack wait -t 30

GitHub Actions Runner

version: 0.2

phases:
  pre_build:
    steps:
      - run: docker pull public.ecr.aws/localstack/localstack:latest
      - run: docker image tag public.ecr.aws/localstack/localstack-pro:latest localstack/localstack:latest
      - name: Start LocalStack
        uses: LocalStack/setup-localstack@v0.2.2
        with:
          image-tag: 'latest'
          install-awslocal: 'true'

Configuration

Get know more about the LocalStack config options.

Native Runner

version: 0.2

env:
  variables:
    DEBUG: 1
...
phases:
...

GitHub Actions Runner

version: 0.2

env:
  variables:
    DEBUG: 1
...

phases:
  pre_build:
    steps:
      ...
      - name: Start LocalStack
        uses: LocalStack/setup-localstack@v0.2.2
        with:
          image-tag: 'latest'
          configuration: LS_LOG=trace
...

Configuring a CI Auth Token

To enable LocalStack Pro features, you need to add your LocalStack CI Auth Token to the project’s environment variables. The LocalStack container will automatically pick it up and activate the licensed features.

Go to the CI Auth Token page and copy your CI Auth Token. To add the CI Auth Token to your CodeBuild project, follow these steps:

• Navigate to your project dashboard, click Edit to open the dropdown, and select Environment.
• Click on Additional configuration and navigate to the Environment variables section.
• Specify Name as LOCALSTACK_AUTH_TOKEN and Value as your CI Auth Token. Specify Type as per your requirement.

Click on Update environment to save your environment variables. Navigate to the buildspec file and change the Docker image to public.ecr.aws/localstack/localstack-pro:latest:

Native Runner

...
phases:
  pre_build:
    commands:
      - pip3 install localstack awscli
      - docker pull public.ecr.aws/localstack/localstack-pro:latest
...

GitHub Actions Runner

...
phases:
  pre_build:
    steps:
      - run: docker pull public.ecr.aws/localstack/localstack-pro:latest
      - run: docker image tag public.ecr.aws/localstack/localstack-pro:latest localstack/localstack-pro:latest
      - name: Start LocalStack
        uses: LocalStack/setup-localstack@v0.2.2
        with:
          image-tag: 'latest'
          use-pro: 'true'
...

Dump LocalStack logs

...
artifacts:
  files:
    - localstack.log

phases:
  pre_build:
    commands:
      # Starts up LocalStack
    ...
  build:
    commands:
      # Run some commands which might fail
      ...
  post_build:
    commands:
      # Dump logs on build fail
      - '[ ${CODEBUILD_BUILD_SUCCEEDING:-0} -eq 0 ] (localstack logs | tee localstack.log) || true'
...
# Optionally store dumped logs as artifact
artifact:
  files:
    - localstack.log

Store LocalStack state

Cloud Pods

Find more information about cloud pods here.

Native Runner

...
phases:
  pre_build:
    commands:
      ...
      # LocalStack is up and running already
      - localstack pod load <POD_NAME> || true
      ...
      - localstack pod save <POD_NAME>
      ...

GitHub Actions Runner

...
phases:
  pre_build:
    steps:
      # LocalStack is up and running already
      - name: Load the Cloud Pod
        continue-on-error: true  # Allow it to fail as pod does not exist at first run
        uses: LocalStack/setup-localstack@v0.2.2
        with:
          state-backend: cloud-pods
          name: <cloud-pod-name>
          action: load
          skip-startup: 'true'
      ...
      - name: Save the Cloud Pod
        uses: LocalStack/setup-localstack@v0.2.2
        with:
          state-backend: cloud-pods
          state-name: <cloud-pod-name>
      ...

Ephemeral Instances (Preview)

...
phases:
  pre_build:
    commands:
      ...
      - |
          response=$(curl -X POST -d '{"auto_load_pod": "false"}' \
            -H 'ls-api-key: $LOCALSTACK_API_KEY' \
            -H 'authorization: token $LOCALSTACK_API_KEY' \
            -H 'content-type: application/json' \
            https://api.localstack.cloud/v1/previews/my-localstack-state)

          if [ "$endpointUrl" = "null" ] || [ "$endpointUrl" = "" ]; then
            echo "Unable to create preview environment. API response: $response"
            exit 1
          fi
          echo "Created preview environment with endpoint URL: $endpointUrl"

          export AWS_ENDPOINT_URL=$endpointUrl
      ...

Find out more about ephemeral instances.

Artifact

Find out more about state management.

...
phases:
  pre_build:
  # LocalStack is up and running already
  - (test -f ./ls-state-pod.zip && localstack state import ./ls-state-pod.zip) || true
  ...
  - localstack state export ./ls-state-pod.zip
...
artifact:
  files:
    - ls-state-pod.zip

Alternatively save as a secondary artifact:

...
artifact:
  ...
  secondary-artifacts:
    ls-state:
      files:
        - ls-state-pod.zip
    ...

To use previously stored artifacts as inputs, set them as a source in the project.

Cache

Additional information about state export and import.

Native Runner

...
phases:
  pre_build:
    commands:
    # LocalStack is up and running already
      - (test -f ./ls-state-pod.zip && localstack state import ./ls-state-pod.zip) || true
      ...
      - localstack state export ./ls-state-pod.zip
...
cache:
  paths:
    - 'ls-state-pod.zip'

GitHub Actions Runner

...
phases:
  pre_build:
    steps:
      - run: (test -f ./ls-state-pod.zip && localstack state import ./ls-state-pod.zip) || true
      ...
      - run: localstack state export ./ls-state-pod.zip
...
cache:
  paths:
    - 'ls-state-pod.zip'

Current Limitations

• We recommend using the public.ecr.aws/localstack/localstack:latest image to start LocalStack, instead of the localstack/localstack:latest image. LocalStack mirrors the Docker Hub image to the public ECR repository. You can use the Docker Hub image as well, though you may run into the following error:

  toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

  To resolve this use your Docker Hub account credentials to pull the image.

• LocalStack depends on the Docker socket to emulate your infrastructure. To enable it, update your project by ticking Environment > Additional Configuration > Privileged > Enable this flag if you want to build Docker Images or want your builds to get elevated privileges.

• AWS states in its documentation GitHub Actions Runners are not available for webhook triggered open Git repositories.

• Be aware that you can only use either the Native Runner or the GitHub Actions Runner snippets in the same phase For further information see the official CodeBuild documentation.