Using images from a private repository in Elastic Beanstalk - AWS Elastic Beanstalk
Amazon ECR repositorySSM Parameter StoreDockerrun.aws.json file

Using images from a private repository in Elastic Beanstalk

This topic describes how to authenticate to a private online image repository with Elastic Beanstalk. Elastic Beanstalk must authenticate with the online registry before it can pull and deploy your images. There are multiple configuration options.

Using images from an Amazon ECR repository

You can store your custom Docker images in AWS with Amazon Elastic Container Registry (Amazon ECR).

When you store your Docker images in Amazon ECR, Elastic Beanstalk automatically authenticates to the Amazon ECR registry with your environment's instance profile. Therefore you'll need to provide your instances with permission to access the images in your Amazon ECR repository. To do so add permissions to your environment's instance profile by attaching the AmazonEC2ContainerRegistryReadOnly managed policy to the instance profile. This provides read-only access to all the Amazon ECR repositories in your account. You also have the option to only access to single repository by using the following template to create a custom policy:

{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AllowEbAuth",
        "Effect": "Allow",
        "Action": [
          "ecr:GetAuthorizationToken"
        ],
        "Resource": [
          "*"
        ]
      },
      {
        "Sid": "AllowPull",
        "Effect": "Allow",
        "Resource": [
          "arn:aws:ecr:us-east-2:account-id:repository/repository-name"
        ],
        "Action": [
          "ecr:GetAuthorizationToken",
          "ecr:BatchCheckLayerAvailability",
          "ecr:GetDownloadUrlForLayer",
          "ecr:GetRepositoryPolicy",
          "ecr:DescribeRepositories",
          "ecr:ListImages",
          "ecr:BatchGetImage"
        ]
      }
    ]
  }

Replace the Amazon Resource Name (ARN) in the above policy with the ARN of your repository.

You'll need to specify the image information in your Dockerrun.aws.json file. The configuration will be different depending on which platform you use.

For the ECS managed Docker platform, use the image key in a container definition object :

"containerDefinitions": [
        {
        "name": "my-image",
        "image": "account-id.dkr.ecr.us-east-2.amazonaws.com/repository-name:latest",

For the Docker platform refer to the image by URL. The URL goes in the Image definition of your Dockerrun.aws.json file:

  "Image": {
      "Name": "account-id.dkr.ecr.us-east-2.amazonaws.com/repository-name:latest",
      "Update": "true"
    },

Using the AWS Systems Manager (SSM) Parameter Store

You can configure Elastic Beanstalk to log in to your private repository before it starts the deployment process. This enables Elastic Beanstalk to access the images from the repository and deploy these images to your Elastic Beanstalk environment.

This configuration initiates events in the prebuild phase of the Elastic Beanstalk deployment process. You set this up in the .ebextentions configuration directory. The configuration uses platform hook scripts that call docker login to authenticate to the online registry that hosts the private repository. A detailed breakdown of these configuration steps follows.

To configure Elastic Beanstalk to authenticate to your private repository with AWS SSM
Note

You need to set up AWS Systems Manager to complete these steps. For more information, see the AWS Systems Manager User Guide

  1. Create your .ebextensions directory structure as follows.

    
├── .ebextensions
│   └── env.config
├── .platform
│   ├── confighooks
│   │   └── prebuild
│   │       └── 01login.sh
│   └── hooks
│       └── prebuild
│           └── 01login.sh
├── docker-compose.yml

  2. Use the AWS Systems Manager Parameter Store to save the credentials of your private repository so that Elastic Beanstalk can retrieve your credentials when required. For this, run the put-parameter command. 

    aws ssm put-parameter --name USER --type String --value "username"
aws ssm put-parameter --name PASSWD --type String --value "passwd"

  3. Create the following env.config file and place it in the .ebextensions directory as shown in the preceding directory structure. This configuration uses the aws:elasticbeanstalk:application:environment namespace to initialize the USER and PASSWD Elastic Beanstalk environment variables to the values in the SSM Parameter Store.

    Note

    USER and PASSWD in the script must match the same strings that are used in the preceding ssm put-parameter commands.

    option_settings:
  aws:elasticbeanstalk:application:environment:
    USER: '{{resolve:ssm:USER:1}}'
    PASSWD: '{{resolve:ssm:PASSWD:1}}'

  4. Create the following 01login.sh script file and place it in the following directories (also shown in the preceding directory structure):

    • .platform/confighooks/prebuild

    • .platform/hooks/prebuild

    ### example 01login.sh
#!/bin/bash
USER=/opt/elasticbeanstalk/bin/get-config environment -k USER
/opt/elasticbeanstalk/bin/get-config environment -k PASSWD | docker login -u $USER --password-stdin

    The 01login.sh script calls the get-config platform script to retrieve the repository credentials. It stores the user name in the USER variable. In the next line, it retrieves the password. Instead of storing the password in a variable, the script pipes the password directly to the docker login command in the stdin input stream. The --password-stdin option uses the input stream, so you don't have to store the password in a variable. For more information about authentication with the Docker command line interface, see docker login on the Docker documentation website.

    Notes

    • All script files must have execute permission. Use chmod +x to set execute permission on your hook files. For all Amazon Linux 2 based platforms versions that were released on or after April 29, 2022, Elastic Beanstalk automatically grants execute permissions to all of the platform hook scripts. In this case you don't have to manually grant execute permissions. For a list of these platform versions, refer to the April 29, 2022 - Linux platform release notes in the AWS Elastic Beanstalk Release Notes Guide.

    • Hook files can be either binary files or script files starting with a #! line containing their interpreter path, such as #!/bin/bash.

    • For more information, see Platform hooks in Extending Elastic Beanstalk Linux platforms.

After Elastic Beanstalk can authenticate with the online registry that hosts the private repository, your images can be deployed and pulled.

Using the Dockerrun.aws.json file

This section describes another approach to authenticate Elastic Beanstalk to a private repository. With this approach, you generate an authentication file with the Docker command, and then upload the authentication file to an Amazon S3 bucket. You must also include the bucket information in your Dockerrun.aws.json file.

To generate and provide an authentication file to Elastic Beanstalk

  1. Generate an authentication file with the docker login command. For repositories on Docker Hub, run docker login:

    $ docker login

    For other registries, include the URL of the registry server:

    $ docker login registry-server-url
    Note

    If your Elastic Beanstalk environment uses the Amazon Linux AMI Docker platform version (precedes Amazon Linux 2), read the relevant information in Docker configuration on Amazon Linux AMI (preceding Amazon Linux 2).

    For more information about the authentication file, see Store images on Docker Hub and docker login on the Docker website.

  2. Upload a copy of the authentication file that is named .dockercfg to a secure Amazon S3 bucket.

    • The Amazon S3 bucket must be hosted in the same AWS Region as the environment that is using it. Elastic Beanstalk cannot download files from an Amazon S3 bucket hosted in other Regions.

    • Grant permissions for the s3:GetObject operation to the IAM role in the instance profile. For more information, see Managing Elastic Beanstalk instance profiles.

  3. Include the Amazon S3 bucket information in the Authentication parameter in your Dockerrun.aws.json file.

    The following example shows the use of an authentication file named mydockercfg in a bucket named amzn-s3-demo-bucket to use a private image in a third-party registry. For the correct version number for AWSEBDockerrunVersion, see the note that follows the example.

    {
  "AWSEBDockerrunVersion": "version-no",
  "Authentication": {
    "Bucket": "amzn-s3-demo-bucket",
    "Key": "mydockercfg"
  },
  "Image": {
    "Name": "quay.io/johndoe/private-image",
    "Update": "true"
  },
  "Ports": [
    {
      "ContainerPort": "1234"
    }
  ],
  "Volumes": [
    {
      "HostDirectory": "/var/app/mydb",
      "ContainerDirectory": "/etc/mysql"
    }
  ],
  "Logging": "/var/log/nginx"
}
    Dockerrun.aws.json versions

    The AWSEBDockerrunVersion parameter indicates the version of the Dockerrun.aws.json file.

    • The Docker AL2 and AL2023 platforms use the following versions of the file.

      • Dockerrun.aws.json v3 — environments that use Docker Compose.

      • Dockerrun.aws.json v1 — environments that do not use Docker Compose.

    • ECS running on Amazon Linux 2 and ECS running on AL2023 uses the Dockerrun.aws.json v2 file. The retired platform ECS-The Multicontainer Docker Amazon Linux AMI (AL1) also used this same version.

After Elastic Beanstalk can authenticate with the online registry that hosts the private repository, your images can be deployed and pulled.