Using the EB CLI with AWS CodeBuild

AWS CodeBuild compiles your source code, runs unit tests, and produces artifacts that are ready to deploy. You can use CodeBuild together with the EB CLI to automate building your application from its source code. Environment creation and each deployment thereafter start with a build step, and then deploy the resulting application.

Note

Some regions don't offer CodeBuild. The integration between Elastic Beanstalk and CodeBuild doesn't work in these regions.

For information about the AWS services offered in each region, see Region Table.

Creating an application

To create an Elastic Beanstalk application that uses CodeBuild

1. Include a CodeBuild build specification file, buildspec.yml, in your application folder.

2. Add an eb_codebuild_settings entry with options specific to Elastic Beanstalk to the file.

3. Run eb init in the folder.

   Note

   Do not use the period (.) or space ( ) characters in Application name when you use the EB CLI with CodeBuild.

Elastic Beanstalk extends the CodeBuild build specification file format to include the following additional settings:

eb_codebuild_settings:
  CodeBuildServiceRole: role-name
  ComputeType: size
  Image: image
  Timeout: minutes    

CodeBuildServiceRole

The ARN or name of the AWS Identity and Access Management (IAM) service role that CodeBuild can use to interact with dependent AWS services on your behalf. This value is required. If you omit it, any subsequent eb create or eb deploy command fails.

To learn more about creating a service role for CodeBuild, see Create a CodeBuild Service Role in the AWS CodeBuild User Guide.

Note

You also need permissions to perform actions in CodeBuild itself. The Elastic Beanstalk AdministratorAccess-AWSElasticBeanstalk managed user policy includes all the required CodeBuild action permissions. If you're not using the managed policy, be sure to allow the following permissions in your user policy.

  "codebuild:CreateProject",
  "codebuild:DeleteProject",
  "codebuild:BatchGetBuilds",
  "codebuild:StartBuild"

For details, see Managing Elastic Beanstalk user policies.

ComputeType

The amount of resources used by the Docker container in the CodeBuild build environment. Valid values are BUILD_GENERAL1_SMALL, BUILD_GENERAL1_MEDIUM, and BUILD_GENERAL1_LARGE.

Image

The name of the Docker Hub or Amazon ECR image that CodeBuild uses for the build environment. This Docker image should contain all the tools and runtime libraries required to build your code, and should match your application's target platform. CodeBuild manages and maintains a set of images specifically meant to be used with Elastic Beanstalk. It is recommended that you use one of them. For details, see Docker Images Provided by CodeBuild in the AWS CodeBuild User Guide.

The Image value is optional. If you omit it, the eb init command attempts to choose an image that best matches your target platform. In addition, if you run eb init in interactive mode and it fails to choose an image for you, it prompts you to choose one. At the end of a successful initialization, eb init writes the chosen image into the buildspec.yml file.

Timeout

The duration, in minutes, that the CodeBuild build runs before timing out. This value is optional. For details about valid and default values, see Create a Build Project in CodeBuild.

Note

This timeout controls the maximum duration for a CodeBuild run, and the EB CLI also respects it as part of its first step to create an application version. It's distinct from the value you can specify with the --timeout option of the eb create or eb deploy commands. The latter value controls the maximum duration that for EB CLI to wait for environment creation or update.

Building and deploying your application code

Whenever your application code needs to be deployed, the EB CLI uses CodeBuild to run a build, then deploys the resulting build artifacts to your environment. This happens when you create an Elastic Beanstalk environment for your application using the eb create command, and each time you later deploy code changes to the environment using the eb deploy command.

If the CodeBuild step fails, environment creation or deployment doesn't start.