Registry v1 API Deprecation

Docker will be disabling pulls via the registry v1 APIs on Docker Hub on June 1 2019. Pushes to Docker Hub via the registry v1 API have been disallowed since November 2015, and pulls via the registry v1 API can only be performed via Docker Clients 1.12 and below. Our goal is to ensure stability of our services and the best experience across our Docker Hub offering, including the registry v2 APIs and other user and account management improvements that are in the works.

At this time, we have found that the number of consumers of the v1 registry API on Docker Hub have fallen below a reasonable threshold, and are on Docker Clients that are no longer supported. Please see below for how to migrate to the registry v2 APIs.

Deprecation Timeline

March 21 2019 : Announce deprecation via blog post and present timeline.

April 12 2019 9:00 am PDT: Pulls from Docker Hub via the registry v1 api will be temporarily blocked for a 5 minute period. Pulls via the registry v1 api will be restored after the 5 minute block.

April 15 2019 9:00 am PDT: Pulls from Docker Hub via the registry v1 api will be temporarily blocked for a 5 minute period. Pulls via the registry v1 api will be restored after the 5 minute block.

April 23 2019 9:00 am PDT: Pulls from Docker Hub via the registry v1 api will be temporarily blocked for a 1 hour period. Pulls via the registry v1 api will be restored after the 1 hour block.

April 30 2019 9:00 am PDT: Pulls from Docker Hub via the registry v1 api will be temporarily blocked for a 2 hour period. Pulls via the registry v1 api will be restored after the 2 hour block.

May 7 2019 9:00 am PDT:  Pulls from Docker Hub via the registry v1 api will be temporarily blocked for a 4 hour period. Pulls via the registry v1 api will be restored after the 4 hour block.

May 15 2019 9:00 am PDT: Pulls from Docker Hub via the registry v1 api will be temporarily blocked for a 24 hour period. Pulls via the registry v1 api will be restored after the 24 hour block.

June 1 2019 : Pulls via the registry v1 api on Docker Hub will be completely turned off.

Using the v2 registry API on Docker Hub

Any existing users of the v1 registry API on Docker Hub can move to the v2 registry API via the following steps

1. Update your Docker Engine to 17.03 or later so it is compatible with the v2 registry API. You may obtain the latest versions of the engine from Docker Hub (Community and Enterprise).
2. If you have content in Docker Hub that is in the v1 format, you may move it to use the v2 format by rebuilding the image using a newer Docker Client (more recent than 1.12) and pushing it to Docker Hub.

Let us know if you have additional questions around your usage of the registry v1 API on Docker Hub and the remediation steps by emailing us at [email protected]. We would like to hear from you and work together to help fix any issues that you might encounter.

Some insights into the whys

We’ve blocked pushes via the registry v1 API for close to four years now, so the current usage numbers for pulls on a per day basis looked something like this:

When compared against traffic coming through the registry v2 API which is the status quo, this accounted for about .15% of the total traffic.

A further breakdown showed us that about 80% of the traffic we were receiving was resulting in 404s and only 15% resulting in successful 2xx transactions. The transactions were originating from a small set of IPs – again, these accounted for under .1% of the number of IPs that are responsible for transactions into the v2 API over the same period of time.

We are aware that a lot of customers depend on Hub staying up and servicing incoming requests, so as part of best practices when deprecating an API despite questionable usage, we’re introducing several brownouts that are 5 minutes in duration with a distinct error message that will direct users to this blogpost so they’re aware of the upcoming change.

Beyond the first set of five minute brownouts, we’ll introduce a couple of hour long brownouts and we’re confident that most users will be able to remediate – our hypothesis is that in most cases the action performed will be shutting down the instance making the v1 API call since the customer has most likely moved on to the v2 registry API already.