Using the Multicontainer Docker platform (Amazon Linux AMI) - AWS Elastic Beanstalk

Using the Multicontainer Docker platform (Amazon Linux AMI)


This platform only supports the Amazon Linux AMI operating system (preceding Amazon Linux 2). Multicontainer Docker functionality on Amazon Linux 2 is provided by the Docker platform and receives long-term support..

If your Elastic Beanstalk Docker environment uses an Amazon Linux AMI platform version (preceding Amazon Linux 2), you can create docker environments that support multiple containers per Amazon EC2 instance with multicontainer Docker platform for Elastic Beanstalk.

Elastic Beanstalk uses Amazon Elastic Container Service (Amazon ECS) to coordinate container deployments to multicontainer 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. The instances in the environment each run the same set of containers, which are defined in a file.


Some regions don't offer Amazon ECS. Multicontainer Docker environments aren't supported in these regions.

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

Multicontainer Docker platform

Standard generic and preconfigured Docker platforms on Elastic Beanstalk support only a single Docker container per Elastic Beanstalk environment. 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: file

Container instances—Amazon EC2 instances running Multicontainer 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. Version 2 adds support for multiple containers per Amazon EC2 instance and can only be used with the multicontainer Docker platform. The format differs significantly from the previous version which is detailed under Docker configuration

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

Docker images

The Multicontainer 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 multicontainer 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 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 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 Management 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 multicontainer Docker platform, Elastic Beanstalk automatically creates and configures several Amazon Elastic Container Service resources while building the environment in order to create 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 multicontainer Docker environment.

  • Amazon ECS Task Definition – Elastic Beanstalk uses the file 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 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 multicontainer 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 file. The following excerpt shows an example:

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

See v2 for details on the 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 multicontainer 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.