Run builds on reserved capacity fleets

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 macOS or 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/.

Topics

• Create a reserved capacity fleet
• Best practices
• Can I share a reserved capacity fleet across multiple CodeBuild projects?
• Which regions support reserved capacity fleets?
• How do I configure a reserved capacity macOS fleet?
• Limitations of reserved capacity fleets
• Reserved capacity fleet properties
• Reserved capacity samples with AWS CodeBuild

Create a reserved capacity fleet

Use the following instructions to create a reserved capacity fleet.

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 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. In the Compute field, 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. (Optional) In Additional configuration do the following:

   • From the VPC - optional drop-down menu, select a VPC that your CodeBuild fleet will access.

   • From the Subnets drop-down menu, select the subnets that CodeBuild should use to set up your VPC configuration.

   • From the Security groups drop-down menu, select the security groups that CodeBuild should use to work with your VPC.

   • In the Fleet Service Role field, choose an existing service role.

     Note

     Make sure that your fleet role has the necessary permissions. For more information, see Allow a user to add a permission policy for a fleet service role.

10. Choose Create compute fleet.

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

Important

When using the reserved capacity feature, data cached on fleet instances, including source files, Docker layers, and cached directories specified in the buildspec, can be accessible to other projects within the same account. This is by design and allows projects within the same account to share fleet instances.

Which regions support reserved capacity fleets?

Reserved capacity Amazon Linux and Windows fleets are 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 macOS Medium fleets are supported in the following AWS Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Asia Pacific (Sydney), and Europe (Frankfurt). Reserved capacity macOS Large fleets are supported in the following AWS Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), and Asia Pacific (Sydney).

How do I configure a reserved capacity macOS fleet?

To configure a reserved capacity macOS 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 Fleet.

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

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

5. In the Compute field, choose one of the following compute machine types: Apple M2, 24 GB memory, 8 vCPUs or Apple M2, 32 GB memory, 12 vCPUs.

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

7. (Optional) If you choose Custom image for your fleet, ensure that your Amazon Machine Images (AMI) has the following prerequisites:

   • The AMI Architecture is 64-bit Mac-Arm.

   • The AMI allows the CodeBuild service Organization ARN. For a list of Organization ARNs, see Amazon Machine Images (AMI).

   • If the AMI is encrypted with a AWS KMS key, the AWS KMS key must also allow the CodeBuild service Organization ID. For a list of Organization IDs, see Amazon Machine Images (AMI). For more information on AWS KMS keys, see Allow organizations and OUs to use a KMS key in the Amazon EC2 User Guide.

   • In the Fleet service role field, grant the following Amazon EC2 permissions:

     {
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Effect": "Allow",
                 "Action": "ec2:DescribeImages",
                 "Resource": "*"
             }
         ]
     }

8. (Optional) To configure a VPC with your fleet, in Additional configuration do the following:

   • From the VPC - optional drop-down menu, select a VPC that your CodeBuild fleet will access.

   • From the Subnets drop-down menu, select the subnets that CodeBuild should use to set up your VPC configuration.

   • From the Security groups drop-down menu, select the security groups that CodeBuild should use to work with your VPC.

   • In the Fleet service role field, choose an existing service role.

     Note

     Make sure that your fleet role has the necessary permissions. For more information, see Allow a user to add a permission policy for a fleet service role.

9. Choose Create compute fleet and wait for the fleet instance to launch. Once launched the capacity will be n/n, where n is the capacity provided.

10. After the compute fleet has launched, 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.

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, or build utilization metrics.

• Reserved capacity macOS fleets don't support debug session.

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