Working with reserved capacity in AWS CodeBuild

CodeBuild offers the following compute fleets:

• On-demand fleets

• Reserved capacity fleets

With on-demand fleets, CodeBuild provides compute for your builds. The machines are destroyed when the build finishes. On-demand fleets are fully managed, and includes automatic scaling capabilities to handle spikes in demand.

Note

On-demand fleets do not support Windows Server 2022.

CodeBuild also offers reserved capacity fleets which contain instances powered by Amazon EC2 that are maintained by CodeBuild. With reserved capacity fleets, you configure a set of dedicated instances for your build environment. These machines remain idle, ready to process builds or tests immediately and reduces build durations. With reserved capacity fleets, your machines are always running and will continue to incur costs as long they're provisioned.

Important

Regardless of how long you run an instance for, reserved capacity fleets incur an initial charge per instance, after which there may be additional associated costs. For more information, see https://aws.amazon.com/codebuild/pricing/.

How do I get started with the reserved capacity fleets?

To create a reserved capacity fleet

1. Sign in to the AWS Management Console and open the AWS CodeBuild console at https://console.aws.amazon.com/codesuite/codebuild/home.

2. In the navigation pane, choose Compute fleets, and then choose Create compute fleet.

3. In the Compute fleet name text field, enter a name for your fleet.

4. From the Operating system drop-down menu, choose the operating system.

5. From the Architecture drop-down menu, choose the architecture.

6. From the Compute drop-down menu, choose the compute machine type for your machine.

7. In the Capacity text field, enter the minimum number of instances in the fleet.

8. In the Overflow behavior field, choose the behavior when demand exceeds the fleet capacity. For more information about these options, see Reserved capacity fleet properties.

9. Choose Create compute fleet.

10. After the compute fleet is created, create a new CodeBuild project or edit an existing one. From Environment, choose Reserved capacity under Provisioning model, and then choose the specified fleet under Fleet name.

Best practices

When using reserved capacity fleets, we recommend that you follow these best practices.

• We recommend using source cache mode to help improve the build performance by caching the source.

• We recommend using Docker layer caching to help improve the build performance by caching existing Docker layers.

Can I share a reserved capacity fleet across multiple CodeBuild projects?

Yes, you can maximize the utilization of a fleet’s capacity by using it across multiple projects.

Which regions support reserved capacity fleets?

Reserved capacity fleets is supported in the following AWS Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Asia Pacific (Mumbai), Asia Pacific (Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), Europe (Frankfurt), Europe (Ireland), and South America (São Paulo). For more information about AWS Regions where CodeBuild is available, see AWS Services by Region.

Reserved capacity fleet properties

A reserved capacity fleet contains the following properties:

Operating system

The operating system. The following operating systems are available:

• Amazon Linux

• Windows Server 2019

• Windows Server 2022

Architecture

The processor architecture. The following architectures are available:

• x86_64

• Arm64

Compute

The compute machine type for each instance. The following machine types are available:

Compute type	Environment computeType value	Environment type value	Memory	vCPUs	Disk space
ARM Small	BUILD_GENERAL1_SMALL	ARM_CONTAINER	4 GB	2	50 GB
ARM Large	BUILD_GENERAL1_LARGE	ARM_CONTAINER	16 GB	8	50 GB
Linux Small ¹	BUILD_GENERAL1_SMALL	LINUX_CONTAINER	3 GB	2	64 GB
Linux Medium ¹	BUILD_GENERAL1_MEDIUM	LINUX_CONTAINER	7 GB	4	128 GB
Linux Large ¹	BUILD_GENERAL1_LARGE	LINUX_CONTAINER	15 GB	8	128 GB
Linux XLarge	BUILD_GENERAL1_XLARGE	LINUX_CONTAINER	70 GB	36	256 GB
Linux 2XLarge	BUILD_GENERAL1_2XLARGE	LINUX_CONTAINER	145 GB	72	824 GB (SSD)
Linux GPU Small	BUILD_GENERAL1_SMALL	LINUX_GPU_CONTAINER	16 GB	4	220 GB
Linux GPU Large	BUILD_GENERAL1_LARGE	LINUX_GPU_CONTAINER	255 GB	32	50 GB
Windows Medium	BUILD_GENERAL1_MEDIUM	WINDOWS_SERVER_2019_CONTAINER	7 GB	4	128 GB
Windows Medium	BUILD_GENERAL1_MEDIUM	WINDOWS_SERVER_2022_CONTAINER	7 GB	4	128 GB
Windows Large	BUILD_GENERAL1_LARGE	WINDOWS_SERVER_2019_CONTAINER	15 GB	8	128 GB
Windows Large	BUILD_GENERAL1_LARGE	WINDOWS_SERVER_2022_CONTAINER	15 GB	8	128 GB

Capacity

The initial number of machines allocated to the fleet, which defines the number of builds that can run in parallel.

Overflow behavior

Defines the behavior when the number of builds exceeds the fleet capacity.

On-demand

Overflow builds run on CodeBuild on-demand.

Important

If you choose to set your overflow behavior to on-demand, note that overflow builds will be billed separately, similar to on-demand Amazon EC2. For more information, see https://aws.amazon.com/codebuild/pricing/.

Queue

Build runs are placed in a queue until a machine is available. This limits additional costs because no additional machines are allocated.

Reserved capacity samples with AWS CodeBuild

These samples can be used to experiment with reserved capacity fleets in CodeBuild.

Topics

• Caching with reserved capacity sample

Caching with reserved capacity sample

A cache can store reusable pieces of your build environment and use them across multiple builds. This sample demonstrated how to enable caching within your build project using reserved capacity. For more information, see Build caching in AWS CodeBuild.

You can start by specifying one or more cache modes in your project settings:

Cache:
        Type: LOCAL
        Modes:
          - LOCAL_CUSTOM_CACHE
          - LOCAL_DOCKER_LAYER_CACHE
          - LOCAL_SOURCE_CACHE

Note

Make sure to enable privileged mode in order to use Docker layer cache.

Your project buildspec settings should look like the following:

version: 0.2
      phases:
        build:
          commands:
            - echo testing local source cache
            - touch /codebuild/cache/workspace/foobar.txt
            - git checkout -b cached_branch
            - echo testing local docker layer cache
            - docker run alpine:3.14 2>&1 | grep 'Pulling from' || exit 1
            - echo testing local custom cache
            - touch foo
            - mkdir bar && ln -s foo bar/foo2
            - mkdir bar/bar && touch bar/bar/foo3 && touch bar/bar/foo4
            - "[ -f foo ] || exit 1"
            - "[ -L bar/foo2 ] || exit 1"
            - "[ -f bar/bar/foo3 ] || exit 1"
            - "[ -f bar/bar/foo4 ] || exit 1"
      cache:
        paths:
           - './foo'
           - './bar/**/*'
           - './bar/bar/foo3'

You can start by running a build with the new project to seed the cache. Once that's complete, you should start another build with an overriding buildspec, similar to the following:

version: 0.2
      phases:
        build:
          commands:
            - echo testing local source cache
            - git branch | if grep 'cached_branch'; then (exit 0); else (exit 1); fi
            - ls /codebuild/cache/workspace | if grep 'foobar.txt'; then (exit 0); else (exit 1); fi
            - echo testing local docker layer cache
            - docker run alpine:3.14 2>&1 | if grep 'Pulling from'; then (exit 1); else (exit 0); fi
            - echo testing local custom cache
            - "[ -f foo ] || exit 1"
            - "[ -L bar/foo2 ] || exit 1"
            - "[ -f bar/bar/foo3 ] || exit 1"
            - "[ -f bar/bar/foo4 ] || exit 1"
      cache:
        paths:
           - './foo'
           - './bar/**/*'
           - './bar/bar/foo3'

Limitations of reserved capacity fleets

There are some use-cases which reserved capacity fleets do not support, and if they impact you, use on-demand fleets instead:

• Reserved capacity fleets don't support batch builds, build utilization metrics, or semantic versioning.

• Reserved capacity fleets don't support VPC connectivity.

For more information on limits and quotas, see Compute fleets.