AWS Elastic Beanstalk
Developer Guide (API Version 2010-12-01)

Multicontainer Docker Environments

You can create docker environments that support multiple containers per instance with multicontainer Docker platform for Elastic Beanstalk.

Elastic Beanstalk uses Amazon EC2 Container Service 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.

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 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 EC2 instance in an Auto Scaling group: File

Multicontainer Docker instances on Elastic Beanstalk 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 instance and can only be used with the multicontainer Docker platform. The format differs significantly from the previous version which is detailed under Single Container 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 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": [
      "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 EC2 Container Service resources while building the environment in order to create the necessary containers on each 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 an autoscaling environment, Elastic Beanstalk initiates a new task whenever an instance is added to the cluster.

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


    ListenerProtocol: HTTP
    InstanceProtocol: HTTP
    InstancePort: 8080

If your environment is running in a custom 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:


    Type: AWS::EC2::SecurityGroupIngress
      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 AWS Management 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.