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

Building container images for Beanstalk Cluster environments

A Beanstalk Cluster environment runs an application from a container image. As with Beanstalk Standard, an application version is deployed to the environment. In a Beanstalk Cluster environment, the application version supplies either an image that Elastic Beanstalk runs as-is or source that Elastic Beanstalk builds into an image. This topic covers the prerequisites, both creation paths, processing status, and the deletion behavior specific to Beanstalk Cluster environments. Deploying, tagging, and version quotas work the same way in both modes, as do the general creation and deletion procedures. See Managing application versions and Tagging application versions.

For a Beanstalk Cluster deployment, create the application version with an ImageConfiguration that carries exactly one of two members. Source identifies a container image that is already built, and Build specifies how Elastic Beanstalk builds an image from a source bundle. Elastic Beanstalk rejects a CreateApplicationVersion request whose ImageConfiguration supplies both members or neither, a request that supplies both ImageConfiguration.Source and a SourceBundle, and a request that combines ImageConfiguration with the BuildConfiguration parameter, which configures Amazon CodeBuild application versions for Beanstalk Standard. The following sections describe each path.

Prerequisites

The examples in this topic use the Amazon CLI. Install and configure it before running the commands; they use the account and Amazon Region in your Amazon CLI configuration. See Before you begin.

Prepare the following resources and access:

Container image input

Supply an ImageConfiguration with a Source member for a container image that is already built and pushed to a registry. Elastic Beanstalk runs the image without a build step. The Source carries a single field, Uri, that points at the image. The image can be in Amazon Elastic Container Registry (Amazon ECR), or in any registry that allows an unauthenticated pull. For a private image, use Amazon ECR: the environment's node role authenticates to it. An application version created from a provided image needs no build, so Elastic Beanstalk records it with the status UNPROCESSED and it is ready to deploy to a Beanstalk Cluster environment.

Elastic Beanstalk records the URI exactly as you supply it, whether it names a tag or a digest. An image that Elastic Beanstalk builds is recorded by digest.

Use this shape when a separate pipeline builds the image or when an image produced by a previous application version is deployed. To have Elastic Beanstalk build the image, provide a source bundle and a Build member as described next.

Provide source for Elastic Beanstalk to build

Supply a SourceBundle when Elastic Beanstalk must build the container image from application source. The SourceBundle identifies the source archive in Amazon Simple Storage Service (Amazon S3) with two fields, S3Bucket and S3Key. A source bundle also requires an ImageConfiguration whose Build member specifies how Elastic Beanstalk converts the source into an image. Set Process to true in the CreateApplicationVersion request to start the build; with the Amazon CLI, use --process. If you omit this setting, the source-based application version remains UNPROCESSED and the build does not start. When processing starts, Elastic Beanstalk builds the image and pushes it to Amazon Elastic Container Registry in your account. For the Docker and buildpack build types and their settings, see Build configuration.

While the build runs, the application version reports the status BUILDING. It moves to PROCESSED when the image is built and pushed, or to FAILED if the build does not succeed.

Build configuration

The Build member of ImageConfiguration accompanies a source bundle and controls how Elastic Beanstalk builds the image. It carries the following fields alongside the build type described next:

The Build member selects one of two build types through its Type field, which is required:

The Architecture field sets the target CPU architecture of the image, either amd64 or arm64. If you omit it, Elastic Beanstalk builds for amd64. Build for the same architecture as the environment's arch setting, which also defaults to amd64. An image built for one architecture does not run on the other. For arch, see Configuration options for Beanstalk Cluster environments.

Inspect and monitor processing status

A source-based version reports BUILDING while Elastic Beanstalk builds its image. Deploy it only after it reports PROCESSED. A status of FAILED means that the build did not succeed and the version cannot be deployed. A status of UNPROCESSED means that processing did not start, such as when the CreateApplicationVersion request omitted Process. An application version created from a provided image also reports UNPROCESSED, but it is ready to deploy because its image requires no build.

A description of an application version reports its image state as two members, ImageSource and ImageBuildConfiguration. For a source-based version, ImageBuildConfiguration echoes the build settings, and ImageSource is absent while the version reports BUILDING. When the build succeeds, ImageSource returns the digest-pinned URI of the image that the build produced and pushed.

Check the processing status of a source-based version with DescribeApplicationVersions. Set operation_start to the timestamp recorded immediately before the CreateApplicationVersion request; the event queries that follow use it to scope events to the build.

$ aws elasticbeanstalk describe-application-versions \
    --application-name my-app \
    --version-labels v1-build \
    --query 'ApplicationVersions[0].Status' \
    --output text

Repeat this command until the version reaches a terminal status. BUILDING means the build is still running. Deploy the version only after it reports PROCESSED; a status of FAILED or UNPROCESSED means that the version cannot be deployed.

For a source-based version, a PROCESSED status and an image-build completion event confirm that Elastic Beanstalk built and recorded the image. Retrieve events for the specific version to distinguish a terminal failure from a build that is still running:

$ aws elasticbeanstalk describe-events \
    --application-name my-app \
    --version-label v1-build \
    --start-time "$operation_start" \
    --max-items 20

If the version reaches FAILED, add --severity ERROR to retrieve its failure events. The events distinguish failures such as source download, role assumption, Amazon ECR authentication, and image build or push failures:

$ aws elasticbeanstalk describe-events \
    --application-name my-app \
    --version-label v1-build \
    --severity ERROR \
    --start-time "$operation_start" \
    --max-items 20

The events identify which stage failed. To see why the build itself failed, use the BuildArn that a source-based version reports, which identifies the Amazon CodeBuild execution that ran the build. Pass it to the following command to get the build's status and the location of its logs:

$ aws codebuild batch-get-builds \
    --ids build-arn \
    --query 'builds[0].{status:buildStatus,logGroup:logs.groupName,logStream:logs.streamName}'

The response also carries a logs.deepLink that opens the build's log stream in the Amazon CloudWatch console.

Correct the source location, build configuration, or role configuration identified by the event. Create a new application version with a new label and Process set to true, then poll it to PROCESSED. Do not deploy a version in FAILED. Processing success proves only that the image is available to the application version; it does not verify an environment deployment.

The sample application

An application version is optional when creating a Beanstalk Cluster environment. When CreateEnvironment is called without a version label (or with a blank one), Elastic Beanstalk deploys a sample application to provide a running environment. Elastic Beanstalk backs the sample with a prebuilt container image, so deployment requires no build step. The sample application cannot be selected or configured as a customer application; Elastic Beanstalk deploys it when no version label is specified. To deploy an application, create an application version as described in this topic and pass its version label to CreateEnvironment. For environment creation, see Getting started with Beanstalk Cluster.

Examples

The following CreateApplicationVersion request provides an existing container image. Elastic Beanstalk runs the image as-is, with no build.

aws elasticbeanstalk create-application-version \
  --application-name my-app \
  --version-label v1-image \
  --image-configuration Source={Uri=111122223333.dkr.ecr.us-east-1.amazonaws.com/my-app:v1}

The following request instead provides a source bundle in Amazon S3 and a build configuration that builds the image from a Dockerfile for the arm64 architecture. To run this image, set the environment's arch option to arm64 as well.

operation_start=$(date -u +%Y-%m-%dT%H:%M:%SZ)
aws elasticbeanstalk create-application-version \
  --application-name my-app \
  --version-label v1-build \
  --process \
  --source-bundle S3Bucket=my-source-bucket,S3Key=my-app/v1.zip \
  --image-configuration '{
    "Build": {
      "Type": "docker",
      "DockerfileLocation": "Dockerfile",
      "Architecture": "arm64",
      "CodeBuildServiceRole": "arn:aws:iam::111122223333:role/my-build-role",
      "ComputeType": "BUILD_GENERAL1_SMALL",
      "TimeoutInMinutes": 30
    }
  }'

The following request builds the image with Cloud Native Buildpacks instead of a Dockerfile. The source needs no Dockerfile, and the builder determines how the image is assembled. The request omits Architecture, so Elastic Beanstalk builds for amd64.

operation_start=$(date -u +%Y-%m-%dT%H:%M:%SZ)
aws elasticbeanstalk create-application-version \
  --application-name my-app \
  --version-label v1-buildpack \
  --process \
  --source-bundle S3Bucket=my-source-bucket,S3Key=my-app/v1.zip \
  --image-configuration '{
    "Build": {
      "Type": "buildpack",
      "Buildpack": "paketobuildpacks/builder-jammy-base",
      "CodeBuildServiceRole": "arn:aws:iam::111122223333:role/my-build-role"
    }
  }'

After a source-bundle build reaches PROCESSED, deploy any of these versions to a Beanstalk Cluster environment by passing its version label to CreateEnvironment or UpdateEnvironment, as for a Beanstalk Standard application version. For configuring the environment that runs it, see Configuring Elastic Beanstalk environments.

Delete and recover application versions

Application version lifecycle policies do not delete Beanstalk Cluster application versions. Use DeleteApplicationVersion to remove an application version record. Elastic Beanstalk rejects the request while the version is BUILDING; wait for a terminal processing status before deleting it.

For a Beanstalk Cluster application version, the DeleteSourceBundle option does not delete the source bundle from Amazon S3. Source-object retention is managed separately.

DeleteApplicationVersion removes the Elastic Beanstalk application version record. It does not delete an image supplied through ImageConfiguration.Source, an image produced by a source build, or the Amazon ECR repository that contains the image. You manage retention of an image that you supplied. When Elastic Beanstalk creates an Amazon ECR repository for source builds, it applies a lifecycle policy to that repository; deleting one application version does not perform immediate image or repository cleanup.

A source-based version in the FAILED state cannot be deployed. Correct the source or build configuration and call CreateApplicationVersion with a new version label and Process set to true. To reuse the failed version's label, first delete the version record after it leaves BUILDING, then create the corrected version.