Hack your own custom domains for Container Registry

If you serve public container images from Container Registry or Artifact Registry, you are exposing your project ID and other details to your users downloading this image. However, by writing a small middleware and running it serverless, you can customize how your registry works.

In this article, I would like to show you how you can develop and run a serverless reverse proxy to customize the behavior of your registry, such as serving your images publicly on your custom domain name instead of gcr.io.

Anatomy of a "docker pull"

Serving container images from a container registry is not magical. All container image registries, such as Google Container Registry, Google Artifact Registry or Docker Hub implement an open API specification. 

Therefore, when you actually run a pull command like: docker pull gcr.io/google-samples/hello:1.0 the underlying container engine (such as Docker Engine) makes bunch of HTTP REST API calls to the REST endpoint like https://gcr.io/v2/google-samples/hello-app/manifests/1.0 to discover details about this image and download the layer blobs. You can use a tools like crane to further inspect how a container registry works when you try to pull or push an image.

Custom domains for your container registry

Serving images on custom domains are especially useful for public images such as open source projects. It also helps you hide the details of the underlying registry (such as gcr.io/*) from your users.

When you use a registry like Container Registry or Artifact Registry to serve images publicly, not only you expose your project IDs to the outside world, you can also end up with really long image names:

docker pull us-central1-docker.pkg.dev/<project-id>/<registry-name>/<image-name>

From the example above, you can see that the name of your container image determines where the registry is hosted and therefore which host the API calls are made. If you were to build a registry that serves images on your custom domain e.g. example.com, you could pull the images by specifying example.com/IMAGE:TAG as the container image reference. In turn, the API requests would be proxied to the actual registry host.

To build such an experience, you can simply use your existing Google Container Registry or Artifact Registry to store your images, and build a "reverse proxy" on top of it to forward the incoming requests while still serving the traffic on the custom domain name you own.

Cloud Run: right tool for the job

Cloud Run is a great fit to host an application like this on Google Cloud. Cloud Run is a serverless container hosting platform and its pricing is especially relevant here, since you only pay for each request served.

In this design, you would be charged only while a request is being handled (i.e. someone is pulling an image), which can easily fit to the free tier.

When you use this proxy with Google Container Registry, actual image layers (blobs) are not not downloaded from the registry API (instead, a Cloud Storage download link is generated for pulling the layer tarball). Since your possibly gigabytes-large layers are not going through this proxy, it is easy to keep the costs low on Cloud Run. 

However, when used with Artifact Registry, since layer blobs of the image are served through this proxy, it will be more costly due to egress networking charges serving larger blobs and longer "billable time" on Cloud Run as a result of proxying large responses during a request.

Building a reverse proxy for your registry

To accomplish this task, I have built a simple reverse proxy using the Go programming language in about 200 lines of code. This proxy uses the httputil.ReverseProxy and adds some special handling around credential negotiation for serving public images (and private images publicly, if you want). 

You can find the example code and deployment instructions at my repository github.com/ahmetb/serverless-registry-proxy. To deploy this proxy to your project to serve public images on your custom domain, refer to the repository for step-by-step instructions. At a high level, you need to:

1. Build the reverse proxy app from its source code into a container image and push it to your registry.
2. Create a Docker registry on Google Container Registry or Artifact Registry, make it publicly accessible to allow serving images without credentials.
3. Deploy the reverse proxy as a publicly-accessible Cloud Run service, while specifying which registry it should be proxying the requests to.
4. Map your domain name to this Cloud Run service on Cloud Console.
5. Cloud Run will now prepare and configure a SSL certificate for your custom domain.
6. After DNS records finish propagating, it's ready to go. Your users can now run: docker pull <YOUR-DOMAIN>/<IMAGE>:<TAG> to download images from your custom domain

Conclusion

You can extend the idea of building "middleware proxies" in front of your container registry and hosting them for cheaply on a serverless platform like Cloud Run with minimal costs.

For example, you can build a registry proxy that serves only particular images or particular tags. Similarly, you can build your own authentication layer on top of an existing registry. Since the Registry API is a standard, my example code works for other container registries such as Docker Hub as well. This way, you can host a serverless proxy on Cloud Run that serves images from Docker Hub or any other registry.

Feel free to examine the source code and fork the project to extend it for your needs. Hopefully this example open source project can also help you serve your container registry on a custom domain.