Use Amazon ECR Public Gallery to Avoid Docker Hub Pull Rate Limits

This article introduces how to switch the repository for obtaining base images to Amazon ECR Public Gallery as a countermeasure when hitting the Docker Hub pull rate limit in CI/CD environments like AWS CodeBuild.

Background

I am using AWS CodeBuild for deployments, and image builds are performed with every deployment. Consequently, pulls for base images residing on Docker Hub (such as go, node, alpine, etc.) occur frequently, and we have increasingly hit rate limits.

Specifically, the following error occurs, causing the deployment to fail:

TOOMANYREQUESTS: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

In this project, we created a dedicated Docker free account for CodeBuild and authenticate before pulling. However, because it is a free account, there is a limit of 200 pulls / 6 hours.

As product development progresses, the frequency of CI/CD deployments has increased, leading to more frequent encounters with this limit. This is a serious problem as it can lead to the inability to perform production deployments, necessitating a solution.

What is Amazon ECR Public Gallery?

To address this, I decided to use Amazon ECR Public Gallery instead of Docker Hub.

Amazon ECR Public Gallery is a container registry that can be used as an alternative to Docker Hub. Amazon mirrors and publishes images from Docker Hub.

https://gallery.ecr.aws/

https://www.docker.com/press-release/docker-official-images-available-amazon-elastic-container-registry/

About ECR Public Gallery Rate Limits and Pricing

Amazon ECR Public Gallery's pull limits and pricing are significantly more relaxed compared to Docker Hub. In particular, when accessed from within an AWS region, there are no limits other than 10 pulls / second, and it can be used for free. This makes it highly attractive for scenarios where pulls from CI/CD systems like CodeBuild are overwhelmingly frequent.

• If not authenticated, per IP address:
  • 10 pulls / second rate limit
  • 500 GB / month data transfer limit
• If authenticated, per account:
  • 10 pulls / second rate limit
  • Free up to 5 TB / month
  • 0.09 USD / GB if exceeding 5 TB / month
  • No data transfer charges if accessed from within an AWS region

Information as of March 11, 2024. Please check the documentation for the latest information.

https://docs.aws.amazon.com/en_us/AmazonECR/latest/public/public-service-quotas.html

https://aws.amazon.com/ecr/pricing/

How to Switch from Docker Hub to ECR Public Gallery

To use Amazon ECR Public Gallery, you need to switch the repository for fetching base images to Amazon ECR Public Gallery using the following steps.

For example, suppose you have a Dockerfile with a FROM clause like this:

FROM node:21.7.0-alpine3.19

node is an official image on Docker Hub. To switch this to an Amazon ECR Public Gallery image, add public.ecr.aws/docker/ and rewrite it as follows:

FROM public.ecr.aws/docker/library/node:21.7.0-alpine3.19

As a point of caution, for official Docker Hub images, you need to append library/ after it. It is important to be careful because forgetting this might lead to referencing a different image. To be safe, please verify the correct image name from the following link:

https://gallery.ecr.aws/docker

With this, it will now reference the Amazon ECR Public Gallery image.

Authentication and Permissions for Using ECR Public Gallery

To avoid the data transfer limit of up to 500 GB/month per IP address that applies when not authenticated, authentication is required.

IAM Policy Settings

To use ECR Public Gallery, permissions for ecr-public:GetAuthorizationToken and sts:GetServiceBearerToken are required. Create a policy like the following and attach it to the IAM user.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AmazonECRPublicGalleryPull",
      "Effect": "Allow",
      "Action": [
        "ecr-public:GetAuthorizationToken",
        "sts:GetServiceBearerToken"
      ],
      "Resource": "*"
    }
  ]
}

https://docs.aws.amazon.com/AmazonECR/latest/public/docker-pull-ecr-image.html

Local Environment

When not authenticated, a data transfer limit of up to 500 GB/month per IP address is applied. Therefore, when referencing images from a local environment, authenticate the account in advance using the following steps.

aws ecr-public get-login-password --region us-west-2 | docker login --username AWS --password-stdin public.ecr.aws

https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html

AWS CodeBuild

When referencing Amazon ECR Public Gallery images in AWS CodeBuild, perform authentication in CodeBuild's buildspec.yml. For example, you can write it in buildspec.yml as follows:

version: 0.2
env:
  variables:
    DOCKER_BUILDKIT: 1
phases:
  pre_build:
    commands:
      - aws ecr-public get-login-password --region us-west-2 | docker login --username AWS --password-stdin public.ecr.aws

Pitfalls

When authenticating, the following error occurred:

Could not connect to the endpoint URL: "https://api.ecr-public.ap-northeast-1.amazonaws.com/"
Error: Cannot perform an interactive login from a non TTY device

This error occurs because the authentication information was not passed from AWS to Docker for some reason. In my case, because I did not specify --region, it was trying to connect to the default region, ap-northeast-1.

ECR Public is only available in us-east-1 or us-west-2, so you must specify one of them using the --region flag. In this instance, I specified us-west-2, which is closer to ap-northeast-1.

https://docs.aws.amazon.com/en_us/general/latest/gr/ecr-public.html

Summary

In this article, I introduced how to switch to Amazon ECR Public Gallery when you hit the Docker Hub pull rate limit.

Especially when accessed from within an AWS region, it can be used for free with virtually no limits, making it very convenient for environments with frequent pulls from CodeBuild.

To prevent similar issues, I will consider switching to Amazon ECR Public Gallery in other projects as well.