Using the Amazon ECS platform branch - AWS Elastic Beanstalk

Using the Amazon ECS platform branch

This topic covers both the Amazon ECS on Amazon Linux 2 platform branch and the platform branch it replaces, Multi-container Docker on AL1 (also ECS managed). Unless otherwise noted, all of the information in this topic applies to both platform branches.


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 Multi-container Docker running on Amazon Linux to ECS on Amazon Linux 2023.

ECS managed Docker platform

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 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:


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

Container instances—Amazon EC2 instances running ECS managed Docker in an Elastic Beanstalk environment—require a configuration file named 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.


Version 1 of the format is used to launch a single Docker container to an Elastic Beanstalk environment running on Amazon Linux AMI, (the version that precedes Amazon Linux 2). The environment is based on the Docker running on 64bit Amazon Linux platform branch, which will be retired on July 18, 2022 . To learn more about the v1 format, see Docker platform Configuration - without Docker Compose.

The Version 2 format of the 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 previous version.

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


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 v2. Note these conventions:

  • Images in official repositories on Docker Hub use a single name (for example, ubuntu or mongo).

  • Images in other repositories on Docker Hub are qualified with an organization name (for example, amazon/amazon-ecs-agent).

  • Images in other online registries are qualified further by a domain name (for example,

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

Container instance role

Elastic Beanstalk uses an Amazon ECS-optimized AMI with an Amazon ECS container agent that runs in a Docker container. The agent communicates with Amazon ECS to coordinate container deployments. In order to communicate with Amazon ECS, each Amazon EC2 instance must have the corresponding permissions in IAM. These permissions are attached to the default instance profile when you create an environment in the Elastic Beanstalk console:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "ECSAccess", "Effect": "Allow", "Action": [ "ecs:Poll", "ecs:StartTask", "ecs:StopTask", "ecs:DiscoverPollEndpoint", "ecs:StartTelemetrySession", "ecs:RegisterContainerInstance", "ecs:DeregisterContainerInstance", "ecs:DescribeContainerInstances", "ecs:Submit*" ], "Resource": "*" } ] }

If you create your own instance profile, you can attach the AWSElasticBeanstalkMulticontainerDocker managed policy to make sure the permissions stay up-to-date. For instructions on creating policies and roles in IAM, see Creating IAM Roles in the IAM User Guide.

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

Using multiple Elastic Load Balancing listeners

You can configure multiple Elastic Load Balancing listeners on a ECS managed Docker environment in order to support inbound traffic for proxies or other services that don't run on the default HTTP port.

Create a .ebextensions folder in your source bundle and add a file with a .config file extension. The following example shows a configuration file that creates an Elastic Load Balancing listener on port 8080.


option_settings: aws:elb:listener:8080: ListenerProtocol: HTTP InstanceProtocol: HTTP InstancePort: 8080

If your environment is running in a custom Amazon Virtual Private Cloud (Amazon VPC) that you created, Elastic Beanstalk takes care of the rest. In a default VPC, you need to configure your instance's security group to allow ingress from the load balancer. Add a second configuration file that adds an ingress rule to the security group:


Resources: port8080SecurityGroupIngress: Type: AWS::EC2::SecurityGroupIngress Properties: GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]} IpProtocol: tcp ToPort: 8080 FromPort: 8080 SourceSecurityGroupName: { "Fn::GetAtt": ["AWSEBLoadBalancer", "SourceSecurityGroup.GroupName"] }

For more information on the configuration file format, see Adding and customizing Elastic Beanstalk environment resources and Option settings.

In addition to adding a listener to the Elastic Load Balancing configuration and opening a port in the security group, you need to map the port on the host instance to a port on the Docker container in the containerDefinitions section of the v2 file. The following excerpt shows an example:

"portMappings": [ { "hostPort": 8080, "containerPort": 8080 } ]

See v2 for details on the v2 file format.

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.