How to work around Docker's new download rate limit on Red Hat OpenShift

Have you recently tried running oc new-app <docker-image>on Red Hat OpenShift and received a similar error message to the one below?

W0216 12:21:52.014221  671649 dockerimagelookup.go:237] container image registry lookup failed: docker.io/username/image:latest: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

If so, you do not need to upgrade your Docker account to a paid one. Instead, you can use a secret to pull your images as an authenticated Docker Hub user.

Docker's new rate limit

Docker recently changed its policy for downloading images as an anonymous user. The company now has a limit of 100 downloads every six hours from a single IP address.

If you are using the OpenShift Developer Sandbox to experiment with a free OpenShift cluster, like I was recently, then you might encounter the error message shown in Figure 1.

You might receive this error message after trying to create a new application with the $ oc new-app command or from the user interface (UI). The issue is that many users are using the same cluster at the same time. Whenever someone tries to create a new application from a Docker image, the cluster downloads the image as an anonymous user, which counts toward the new rate limit. Eventually, the limit is reached, and the error message pops up.

Fortunately, the workaround is easy.

Authenticate to your Docker Hub account

All you have to do to avoid Docker's new rate-limit error is authenticate to your Docker Hub account. After you've authenticated to the account, you won't be pulling the image as an anonymous user but as an authenticated user. The image download will count against your personal limit of 200 downloads per six hours instead of the 100 downloads shared across all anonymous cluster users.

You can use the following command to authenticate:

$ oc create secret docker-registry docker --docker-server=docker.io --docker-username=<username> --docker-password=<password> --docker-email=<email>
$ oc secrets link default docker --for=pull
$ oc new-app <username>/<image> --source-secret=docker

Note that it is recommended that you use an access token here instead of your actual password. Using an access token is also the only way to authenticate if you have two-factor authentication set up on your account.

If you prefer to use the UI, as I do, click Create an image pull secret, as shown in Figure 2.

Either way, you can quickly create an image pull secret, authenticate to your Docker Hub account, and get back to experimenting in the OpenShift Developer Sandbox.

Conclusion

Docker's new download rate limit has caught a few of us by surprise, but the workaround is easy. This article showed you how to use a secret to pull your images as an authenticated Docker Hub user. Once you've done that, you will be able to download images without hitting the rate limit error.