Working with reserved capacity in Amazon CodeBuild - Amazon CodeBuild
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with reserved capacity in Amazon 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://www.amazonaws.cn/codebuild/pricing/.

How do I get started with the reserved capacity fleets?

To create a reserved capacity fleet
  1. Sign in to the Amazon Web Services Management Console and open the Amazon CodeBuild console at https://console.amazonaws.cn/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 Amazon Web Services 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 Amazon Web Services Regions where CodeBuild is available, see Amazon 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://www.amazonaws.cn/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 Amazon CodeBuild

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

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 Amazon 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.