How to Set Up a Registry Proxy Cache with Docker Open Source Registry

One of the latest beta features of the open source Docker v2 Registry is the ability to act as a registry proxy cache for images hosted at Docker Hub. Running a registry cache allows you to store images locally, reducing redundant image pulls across the Internet from Docker Hub. This capability is helpful for users with a large amount of Docker Engines in their environment. Instead of having each Engine pull from the Docker Hub all the time, by following this tutorial you can allow these Engines to pull from the local registry proxy cache to save time and bandwidth.

Here’s how you can get started:

Requirements

Docker Engine 1.8.3
Docker Registry v2
Disk space to store Docker images
TLS certificate and key

Persistent data

In this example, we will assume that you are storing all of our persistent data on your local filesystem in the directory /data. This will include TLS certificate and key, configuration file, and cached images. We will mount this into the registry container later using a volume.

Securing your registry proxy cache

A registry proxy cache needs a TLS certificate to secure connections between the engines and registry hosting the cache. In this example, we will place our certificate (domain.crt) and key (domain.key) on our host in the /data directory. For additional information on securing a registry using TLS, see the Docker Registry 2.0 documentation.

Create a v2 registry proxy cache configuration

Next you will need to create a configuration file for the registry to act as a registry proxy cache. You can retrieve the default registry configuration file from the registry:2 image by using cat and a file redirection to create the configuration file:

$ docker run -it --rm --entrypoint cat registry:2 \
/etc/docker/registry/config.yml > /data/config.yml

I highly suggest retrieving the default configuration from the Docker image instead of using my example configuration as updates to the default configuration may occur over time.

Example default config.yml:

version: 0.1
log:
   fields
      service: registry
storage:
      cache:
         layerinfo: inmemory
      filesystem:
         rootdirectory: /var/lib/registry
http:
   addr: :5000

Update the ‘http’ section to configure TLS:

http:
      addr: :5000
      tls:
            certificate: /var/lib/registry/domain.crt
            key: /var/lib/registry/domain.key

Add a ‘proxy’ section to your configuration file to enable the cache

Click here for the documentation
proxy:
      remoteurl: https://registry-1.docker.io
      username: [username]
      password: [password]

 

The ‘username’ and ‘password’ settings are optional. Providing a Docker Hub username and password will allow the registry proxy cache to store any private images hosted on Docker Hub that are accessible from that account. Any images accessible by that user will be accessible through your image cache.

Be sure to fully understand the implications of providing Docker Hub credentials and ensure your mirror is secure and access is restricted! If you are unsure, do not include a username and password and your registry proxy cache will only cache public images.

Start your registry proxy cache container

$ docker run -d --restart=always -p 5000:5000 --name v2-mirror \
-v /data:/var/lib/registry registry:2 /var/lib/registry/config.yml

 

The above command utilizes a volume to mount /data from our host into the container allowing for persistent storage of cached images, TLS certificate and key, and customized registry configuration.

Verify your registry proxy cache is up and running

$ curl -I https://mycache.example.com:5000/v2/
HTTP/1.1 200 OK
Content-Length: 2
Content-Type: application/json; charset=utf-8
Docker-Distribution-Api-Version: registry/2.0
Date: Thu, 17 Sep 2015 21:42:02 GMT

Configure your Docker Engines to use the registry proxy cache

Update your Docker daemon arguments to include the --registry-mirror option:

--registry-mirror=https://<my-docker-mirror-host>:<port-number>

 

For example, if your host is named mycache.example.com and is running on port 5000, you would add the following option to the daemon arguments:

--registry-mirror=https://mycache.example.com:5000

 

Refer to Configuring and running Docker on various distributions for more info on how to add daemon arguments.

Test your registry proxy cache

Pull an image from Docker Hub you currently do not have stored locally. For example, the busybox:latest image:

$ docker pull busybox:latest

 

Check the catalog to verify that the busybox image has been cached:

$ curl https://mycache.example.com:5000/v2/_catalog
{"repositories":["library/busybox"]}

 

You can also verify that the latest tag has been cached:

$ curl https://mycache.example.com:5000/v2/library/busybox/tags/list
{"name":"library/busybox","tags":["latest"]}

 

Images will now be saved to your registry proxy cache as you pull them. Subsequent image pulls of images that have identical image manifests will be faster and the cache will maintain itself, purging images as they are no longer utilized.

For more information, check out the documentation.

Download Docker Engine and try to set up a Registry Proxy Cache with Docker Open Source Registry!

 

Watch this video from DockerCon 2015 with Stephen Day to learn more about Docker Registry

Slides from Stephen’s talk


 

 Learn More about Docker

• New to Docker? Try our 10 min online tutorial
• Sign up for a free 30 day trial of Docker
• Share images, automate builds, and more with a free Docker Hub account
• Read the Docker 1.8 Release Notes
• Subscribe to Docker Weekly
• Register for upcoming Docker Online Meetups
• Attend upcoming Docker Meetups
• Register for DockerCon Europe 2015
• Start contributing to Docker

 

,

How to Set Up a Registry Proxy Cache with Docker Open Source Registry


8 Responses to “How to Set Up a Registry Proxy Cache with Docker Open Source Registry”

  1. K C

    If you want to cache pulls, but still want to push to Docker Hub, is there a way to use this? (I get a big “UNSUPPORTED” on pushes.)

    Reply
  2. 22-11-2015 - Links - Magnus Udbjørg

    […] How to Set Up a Registry Proxy Cache with Docker Open Source Registry […]

    Reply
  3. Navjot

    Hi,
    I have tried the steps but with docker 1.9 version.
    The images are not getting cached when I checked with curl command.

    Is it compatible with docker v1.9?

    Reply
  4. Singh

    Hi,
    Thanks for the blog.

    Using certificates is optional, right?
    I have tried it without certificates, it seems to be working fine for me.

    Thanks.

    Reply
    • hanxirui

      Can you show me the configuration.I also want tried it without certificates.

      Thanks.

      Reply
  5. Robson Peixoto

    The the TLS really required ?
    My servers will access the mirror only in a private network.

    Reply
  6. Christoph

    How do you configure the mirror registry if it is running behind a firewall?

    Reply
  7. Mick Sear

    I am proxying a company internal Docker registry running API V2.0 using the config from your blog entry, and I can see the request being proxied by tailing the proxying docker registry logs.

    The proxy is requesting http.request.uri="/v2/library/my-image/manifests/latest" from the upstream, but I get an error: level=error msg="response completed with error" err.code="manifest unknown" err.detail="unknown tag=latest". The URL is is requesting is http.request.uri="/v2/library/my-image/manifests/latest", which does not seem to be a valid URL if I request it directly from the origin.

    However, the image does exist and I can pull it directly from the upstream. Is this some kind of API version incompatibility, do you think? Have you seen it before?

    Reply

Leave a Reply

Get the Latest Docker News by Email

Docker Weekly is a newsletter with the latest content on Docker and the agenda for the upcoming weeks.