Using the ECS-managed Docker platform branch in Elastic Beanstalk

This topic provides information about the ECS-managed Docker platform branches for Amazon Linux 2 and Amazon Linux 2023. It also applies to the retired platform branch Multi-container Docker on AL1 (also ECS managed), if you're planning to migrate it to one of the supported platform branches.

Note

On July 18,2022, Elastic Beanstalk set the status of all platform branches based on Amazon Linux AMI (AL1) to retired.

Migration from Multi-container Docker on AL1

If you're presently using the retired Multi-container Docker running on AL1 platform branch, you can migrate to the latest ECS Running on AL2023 platform branch. The latest platform branch supports all of the features from the discontinued platform branch. No changes to the source code are required. For more information, see Migrating your Elastic Beanstalk application from ECS managed Multi-container Docker on AL1 to ECS on Amazon Linux 2023.

ECS managed Docker platform overview

Elastic Beanstalk uses Amazon Elastic Container Service (Amazon ECS) to coordinate container deployments to ECS managed Docker environments. Amazon ECS provides tools to manage a cluster of instances running Docker containers. Elastic Beanstalk takes care of Amazon ECS tasks including cluster creation, task definition and execution. Each of the instances in the environment run the same set of containers, which are defined in a Dockerrun.aws.json v2 file. In order to get the most out of Docker, Elastic Beanstalk lets you create an environment where your Amazon EC2 instances run multiple Docker containers side by side.

The following diagram shows an example Elastic Beanstalk environment configured with three Docker containers running on each Amazon EC2 instance in an Auto Scaling group:

Note

Elastic Beanstalk offers extensibility features for all of its platforms that you can use to customize the deployment and running of your applications. For the ECS running on Amazon Linux 2 platform branch, the instance deployment workflow implementation of these features varies from the other platforms. For more information, see Instance deployment workflow for ECS running on Amazon Linux 2 and later.

Amazon ECS resources created by Elastic Beanstalk

When you create an environment using the ECS managed Docker platform, Elastic Beanstalk automatically creates and configures several Amazon Elastic Container Service resources while building the environment. In doing so, it creates the necessary containers on each Amazon EC2 instance.

• Amazon ECS Cluster – Container instances in Amazon ECS are organized into clusters. When used with Elastic Beanstalk, one cluster is always created for each ECS managed Docker environment.

• Amazon ECS Task Definition – Elastic Beanstalk uses the Dockerrun.aws.json v2 in your project to generate the Amazon ECS task definition that is used to configure container instances in the environment.

• Amazon ECS Task – Elastic Beanstalk communicates with Amazon ECS to run a task on every instance in the environment to coordinate container deployment. In a scalable environment, Elastic Beanstalk initiates a new task whenever an instance is added to the cluster. In rare cases you may have to increase the amount of space reserved for containers and images. Learn more in the Configuring Elastic Beanstalk Docker environments section.

• Amazon ECS Container Agent – The agent runs in a Docker container on the instances in your environment. The agent polls the Amazon ECS service and waits for a task to run.

• Amazon ECS Data Volumes – Elastic Beanstalk inserts volume definitions (in addition to the volumes that you define in Dockerrun.aws.json v2 into the task definition to facilitate log collection.

  Elastic Beanstalk creates log volumes on the container instance, one for each container, at /var/log/containers/containername. These volumes are named awseb-logs-containername and are provided for containers to mount. See Container definition format for details on how to mount them.

Dockerrun.aws.json v2 file

The container instances require a configuration file named Dockerrun.aws.json. Container instances refers to Amazon EC2 instances running ECS managed Docker in an Elastic Beanstalk environment. This file is specific to Elastic Beanstalk and can be used alone or combined with source code and content in a source bundle to create an environment on a Docker platform.

Note

The Version 2 format of the Dockerrun.aws.json adds support for multiple containers per Amazon EC2 instance and can only be used with an ECS managed Docker platform. The format differs significantly from the other configuration file versions that support the Docker platform branches that aren't managed by ECS.

See the Dockerrun.aws.json v2 for details on the updated format and an example file.

Docker images

The ECS managed Docker platform for Elastic Beanstalk requires images to be prebuilt and stored in a public or private online image repository before creating an Elastic Beanstalk environment.

Note

Building custom images during deployment with a Dockerfile is not supported by the ECS managed Docker platform on Elastic Beanstalk. Build your images and deploy them to an online repository before creating an Elastic Beanstalk environment.

Specify images by name in Dockerrun.aws.json v2.

To configure Elastic Beanstalk to authenticate to a private repository, include the authentication parameter in your Dockerrun.aws.json v2 file.

Failed container deployments

If an Amazon ECS task fails, one or more containers in your Elastic Beanstalk environment will not start. Elastic Beanstalk does not roll back multi-container environments due to a failed Amazon ECS task. If a container fails to start in your environment, redeploy the current version or a previous working version from the Elastic Beanstalk console.

To deploy an existing version

1. Open the Elastic Beanstalk console in your environment's region.

2. Click Actions to the right of your application name and then click View application versions.

3. Select a version of your application and click Deploy.