/serverless-registry-proxy

Serverless reverse proxy for exposing container registries (Docker Hub, GCR etc) on custom domains

Primary LanguageGoApache License 2.0Apache-2.0

Serverless Container Registry Proxy

This project offers a very simple reverse proxy that lets you expose your public or private Docker registries (such as Google Container Registry gcr.io, or Docker Hub account) as a public registry on your own domain name.

You can also fork this project and customize as a middleware and deploy to Cloud Run or somewhere else since it’s a generic docker-registry proxy.

Run on Google Cloud

For example, if you have a public registry, and offering images like:

docker pull gcr.io/ahmetb-public/busybox

You can use this proxy, and instead offer your images ✨way fancier🎩, like:

docker pull r.ahmet.dev/busybox

architecture diagram

Building

Download the source code, and build as a container image:

docker build --tag gcr.io/[YOUR_PROJECT]/gcr-proxy .

Then, push to a registry like:

docker push gcr.io/[YOUR_PROJECT]/gcr-proxy

Deploying (to Google Cloud Run) for GCR.io

You can easily deploy this as a serverless container to Google Cloud Run. This handles many of the heavy-lifting for you.

  1. Build and push docker images (previous step)
  2. Deploy to Cloud Run.
  3. Configure custom domain.
    1. Create domain mapping
    2. Verify domain ownership
    3. Update your DNS records
  4. Have fun!

To deploy this to Cloud Run, replace [GCP_PROJECT_ID] with the project ID of the GCR registry you want to expose publicly:

gcloud beta run deploy \
    --allow-unauthenticated \
    --image "[IMAGE]" \
    --set-env-vars "REGISTRY_HOST=gcr.io,REPO_PREFIX=[GCP_PROJECT_ID]"

This will deploy a proxy for your gcr.io/[GCP_PROJECT_ID] public registry. If your GCR registry is private, see the section below on "Exposing private registries".

Then create a domain mapping by running (replace the --domain value):

gcloud beta run domain-mappings create \
    --service gcr-proxy \
    --domain reg.ahmet.dev

This command will require verifying ownership of your domain name, and have you set DNS records for your domain to point to Cloud Run. Then, it will take some 15-20 minutes to actually provision TLS certificates for your domain name.

Deploying (elsewhere)

...is much harder. You need to deploy the application to an environment like Kubernetes, obtain a valid TLS certificate for your domain name, and make it publicly accessible.

Using with other Docker Registries

If you set REGISTRY_HOST and REGISTRY_PREFIX environment variables, you can also use this proxy for other docker registries.

For example, to proxy docker pull ahmet/example to Docker Hub, specify environment variables:

  • REGISTRY_HOST=index.docker.io
  • REPO_PREFIX=ahmet

Note: This is not tested with registries other than Docker Hub and GCR.io. If you can make it work with Azure Container Registry or AWS Elastic Container Registry, contribute examples here.

Exposing private registries publicly (GCR.io)

⚠️ This will make images in your private GCR registries publicly accessible on the internet.

  1. Create an IAM Service Account.

  2. Give it permissions to access the GCR registry GCS Bucket. (Or simply, you can give it the project-wide Storage Object Viewer role.)

  3. Copy your service account JSON key into the root of the repository as key.json.

  4. (Not ideal, but whatever) Rebuild the docker image with your service account key JSON in it. This will require editing Dockerfile to add COPY and ENV directives like:

    COPY key.json /app/key.json
    ENV GOOGLE_APPLICATION_CREDENTIALS /app/key.json
    ENTRYPOINT [...]
    

    You need to rebuild and deploy the updated image.

Configuration

While deploying, you can set additional environment variables for customization:

Key Value
REGISTRY_HOST specify hostname for target registry, e.g. gcr.io.
DISABLE_BROWSER_REDIRECTS if you set this variable to any value, visiting example.com/image on this browser will not redirect to [REGISTRY_HOST]/[REPO_PREFIX]/image to allow your users to browse the image on GCR. If you're exposing private registries, you might want to set this variable.
AUTH_HEADER The Authentication: [...] header’s value to authenticate to the target registry
GOOGLE_APPLICATION_CREDENTIALS (For gcr.io) Path to the IAM service account JSON key file to expose the private GCR registries publicly.

This is not an official Google project. See LICENSE.