Rate Limiting by the Numbers

Donnie Berkholz

Nov 17 2020

As a critical part of Docker’s transition into sustainability, we’ve been gradually rolling out limits on docker pulls to the heaviest users of Docker Hub. As we near the end of the implementation of the rate limits, we thought we’d share some of the facts and figures behind our effort. Our goal is to ensure that Docker becomes sustainable for the long term, while continuing to offer developers 100% free tools to build, share, and run their applications.

We announced this plan in August with an effective date of November 1. We also shared that “roughly 30% of all downloads on Hub come from only 1% of our anonymous users,” illustrated in this chart:

This shows the dramatic impact that a very small percentage of anonymous, free users have on all of Docker Hub. That excessive usage by just 1%–2% of our users results not only in an unsustainable model for Docker but also slows performance for the other 98%–99% of the 11.3 million developers, CI services, and other platforms using Docker Hub every month. Those developers rely upon us to save and share their own container images, as well as to pull images from Docker Verified Publishers and our own trusted library of Docker Official Images, amounting to more than 13.6 billion pulls per month.

Based on our goal of ensuring the vast majority of developers can remain productive, we designed limits of 100 or 200 pulls in a 6-hour window for anonymous and authenticated free users, respectively. In the context of a developer’s daily workflow, 100 pulls in 6 hours amounts to a docker pull every 3.6 minutes on average, for 6 consecutive hours. We considered this more than adequate for an individual developer, while other use cases involving high pull rates such as CI/CD pipelines or production container platforms can decrease their usage or subscribe to a paid plan.

Over the course of a month, a single anonymous developer can (with the help of automation) make up to 12,000 docker pulls. By authenticating, that number increases to 24,000 docker pulls for free. As Docker container images vary in size from a few MB to well above 1 GB, focusing on pulls rather than size provides predictability to developers. They can pull images as they’re building applications, without worrying about their size but rather about their value.

Based on these limits, we expected only 1.5% of daily unique IP addresses to be included — roughly 40,000 IPs in total, out of more than 2 million IPs that pull from Docker Hub every day. The other 98.5% of IPs using Docker Hub can carry on unaffected — or more likely, receive improved performance as the heaviest users decreased.

As November 1st approached, we created a rollout plan that provided additional advance notice and decreased impact — even to developers we haven’t been able to reach through our emails or blog posts. We’ve put a few things in place to ease the transition for anyone affected:

  • Providing a grace period after November 1 prior to full enforcement for all usage, so only a small fraction of the heaviest users were limited early in our rollout;
  • Progressive rollout of enforcement across the affected population, to provide for additional opportunities for communications to reach Docker developers, and to minimize any inadvertent impact; and
  • Temporary time windows of full enforcement, to raise awareness of unknown reliance upon Docker Hub and to reach developers without Docker IDs who we could not otherwise.

On Wednesday, November 18, we expect to complete our progressive rollout to the new limits of 100 pulls and 200 pulls per 6-hour window for anonymous and authenticated free users, respectively. At that point, anyone who has not yet encountered the limits can reasonably conclude that their current usage of docker pulls is in that 98.5% of unaffected Docker Hub users.

As we’ve progressed down this path toward creating a sustainable Docker, we’ve heard multiple times from developers that the temporary full-enforcement windows were valuable. They surfaced unknown reliance upon Docker Hub, as well as areas where our paying customers had not yet authenticated their usage. We’ve also worked with customers to identify problems that were unknowingly causing some of the massive downloads, like runaway processes downloading once every 3 seconds. Alongside this, we’ve created additional paid offerings to support large enterprises, ISVs, and service providers with needs like IP whitelisting or namespace whitelisting.

We greatly appreciate the trust placed in Docker by the entire software community, and we look forward to helping you continue to build the great applications of the future!