whitfin/aws-ecr-proxy repository overview

⁠AWS ECR Proxy

The AWS ECR Proxy is a very simple Nginx proxy to allow forwarding requests through to Amazon ECR. Responses are cached locally to optimize throughput, and credentials can be handled by either key/secret pairs or AWS instance roles.

This project was originally based on the existing aws-ecr-http-proxy⁠ repository. As that project has not had any major changes in a few years and appears to no longer be maintained (at least for now), this repository was separated out as some of the planned changes will be incompatible moving forward (and to separate issues, PRs, etc).

The original forked code will live on the legacy branch as a point of reference, and the main will carry the new line of changes. Obviously major credit goes to the original author(s)!

⁠Basic Usage

Below is a minimal example of running the proxy using an AWS key/secret pair. These are the minimal set of parameters you need to supply if using the defaults for all other values.

docker run \
  -d \
  --net host \
  --name docker-registry-proxy \
  -e "AWS_REGION=${AWS_DEFAULT_REGION}" \
  -e "AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}" \
  -e "AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}" \
  -e "PROXY_ECR_ENDPOINT=https://XXXXXXXXXX.dkr.ecr.eu-central-1.amazonaws.com" \
  -v /tmp/cache:/cache \
  whitfin/aws-ecr-proxy:latest

If you are going to use IAM roles instead, you can omit the key/secret pair and set AWS_INSTANCE_AUTH=true. Assuming your container is running on localhost, you can now access your ECR images:

docker pull localhost:5000/my-ecr-image

The layers will be cached in Nginx to avoid re-pulling them from ECR repeatedly, in theory saving bandwidth and reducing latency.

⁠Configuration

The AWS ECR Proxy is packaged into a Docker container. As such, most configuration is done by providing environment variables at container startup. The following values are currently supported:

If you require further customization of the Nginx configuration, you can provide files inside the Nginx configuration directory located at /usr/local/openresty/nginx/conf. These files will be loaded into the Nginx configuration (store in subdirectories as necessary):

These configurations will be loaded automatically by Nginx on startup, allowing you to configure log formats, payload sizes, etc. based on your desired deployment.

⁠Namespace Exclusion

It's possible you have many images in AWS ECR, and you only wish to proxy through to some of them. For this case you can set PROXY_NAMESPACE_PATTERN, which accepts a regular expression to match namepaces to allow.

For example, if I have 3 images in ECR (image1, image2 and image3), here is how I can exclude the second image easily:

PROXY_NAMESPACE_PATTERN="(image1|image3)"

Please note that this parameter is used to configure routes in Nginx, so your pattern has to be compatible with Nginx's matching. As such, this option should be considered experimental for the time being, but if it works for you it will be safe to use.

⁠TLS/SSL Support

By default the proxy uses plain HTTP, so if you're running the proxy on a remote host Docker will probably complain. You can either enable SSL/TLS by providing a key and certificate, or you can mark your proxy registry as insecure in the Docker configuration.

If you're using this proxy as a sidecar service running on localhost, there is no need to worry about TLS/SSL support. This could be the case for something like Nexus OSS.

If you'd like more details here, there is some information on this in the official Docker documentation⁠.