Proxy Cache Projects

Why Use Container Registry as a Proxy Cache

Container Registry can be used as a proxy cache for images originally stored on Docker Hub.
There are a few reasons why you would avoid pulling images from Docker Hub directly.

Docker Rate Limit

Docker Hub has a download limit rate which is defined differently for different subscription plans. In our blog post, we explain why you can hit the limits quite quickly and which consequences it may have for your workflows.
One of the main reasons why your rate limit may get exhausted is that you often make duplicate (triplicate, etc.) pull requests. A proxy cache prevents duplicate requests. It caches an image that was already pulled and allows you to pull it again from its “cache memory” without sending the actual pull request to Docker Hub.
Nevertheless, you can be sure that you get the latest image version. The proxy accessed the canonical repository and checks if there are newer layers. If yes, then it will pull them, meaning that this request will contribute to the exhaustion of your limit.


To explain it in a different way:
pulling an image from Docker Hub means sending a GET request, whereas the proxy only sends a HEAD request which does not count into the rate limit exhaustion.

Less Bandwidth and no Throttling

Sending too many pull requests may eat into your own bandwidth and slow down your network, as well as lead to your being throttled by the server that hosts the original registry.

Have Better Control and Enjoy Better Security

By using Container Registry, you avoid putting all eggs in one basket: fetching all your images from one place. The opposite situation may make you subject to outages and other failures.

Overcome Outages and Air Gaps

An outage means that you are left without Internet access. But sometimes your access is restricted permanently. To overcome this, you can use proxy cache: it will access the canonical repository for you and supply you with the images you need. Your own machine remains disconnected from vulnerable public networks.

Important Prerequisites

Project admins cannot create proxy projects. You have to be a system admin. Apart from this, you will need to create an endpoint as explained here before. This section also provides information about supported third-party solutions.

Create a New Proxy Cache Project

  • In the navigation, click on Projects and then on + New Project.
  • In the open dialogue window, use the Proxy Cache slider to make this project a proxy cache.
  • Select the endpoint from the dropdown.

To Make Your Proxy Cache Project Work

You are just one more step away from using your new proxy cache.

Edit your docker pull commands: replace canonical registry and project with the proxy project.

Optionally, re-configure your pod manifests in a similar manner.

The last two actions are necessary to pull images from the proxy and not directly from the canonical registry.


  1. Remember that proxy cache projects are only for pulling images.
  2. By granting users access to a proxy cache project, you automatically grant them access to the canonical registry, and they can pull any images from there.

Retention Rules for Proxy-Cached Images

Contrary to other solutions, Container Registry won’t create any retention rules for your proxy cache projects automatically. It means that not only the latest but all images will be kept.
If you want unused images to be deleted from time to time, you can create retention rules as described here.