VOOZH about

URL: https://thenewstack.io/bypass-docker-hub-rate-limits-with-this-stateless-image-cache/

⇱ Spegel: A Stateless Cache for Locally Storing Image Artifacts - The New Stack


TNS
SUBSCRIBE
Join our community of software engineering leaders and aspirational developers. Always stay in-the-know by getting the most important news and exclusive content delivered fresh to your inbox to learn more about at-scale software development.
REQUIRED
It seems that you've previously unsubscribed from our newsletter in the past. Click the button below to open the re-subscribe form in a new tab. When you're done, simply close that tab and continue with this form to complete your subscription.
The New Stack does not sell your information or share it with unaffiliated third parties. By continuing, you agree to our Terms of Use and Privacy Policy.
Welcome and thank you for joining The New Stack community!
Please answer a few simple questions to help us deliver the news and resources you are interested in.
REQUIRED
REQUIRED
REQUIRED
REQUIRED
REQUIRED
Great to meet you!
Tell us a bit about your job so we can cover the topics you find most relevant.
REQUIRED
REQUIRED
REQUIRED
REQUIRED
REQUIRED
Welcome!

We’re so glad you’re here. You can expect all the best TNS content to arrive Monday through Friday to keep you on top of the news and at the top of your game.

What’s next?

Check your inbox for a confirmation email where you can adjust your preferences and even join additional groups.

Follow TNS on your favorite social media networks.

Become a TNS follower on LinkedIn.

Check out the latest featured and trending stories while you wait for your first TNS newsletter.

PREV
1 of 2
NEXT
VOXPOP
As a JavaScript developer, what non-React tools do you use most often?
Angular
0%
Astro
0%
Svelte
0%
Vue.js
0%
Other
0%
I only use React
0%
I don't use JavaScript
0%
Thanks for your opinion! Subscribe below to get the final results, published exclusively in our TNS Update newsletter:
NEW! Try Stackie AI
From clobbered drafts to real-time sync
Apr 14th 2026 10:00am, by David Moore
TypeScript 6.0 RC arrives as a bridge to a faster future
Mar 14th 2026 9:00am, by Darryl K. Taft
Mastra empowers web devs to build AI agents in TypeScript
Jan 28th 2026 11:00am, by Loraine Lawson
2025-02-21 08:00:22
Spegel: A Stateless Cache for Locally Storing Image Artifacts
Cloud Native Ecosystem / Containers / Kubernetes

Spegel: A Stateless Cache for Locally Storing Image Artifacts

Bypass the latest Docker Hub rate limits with this stateless image cache.
Feb 21st, 2025 8:00am by Joab Jackson
👁 Featued image for: Spegel: A Stateless Cache for Locally Storing Image Artifacts

For those running a small, experimental cluster at home, these repository limits can be a “major pain point,”  noted developer  Philip Laine,

Laine is the author of Spegel, an open source project that brings peer-to-peer file sharing to the world of container registries.

Spegel can help the hobbyists keep under their allotment, as well as help larger organization deploy their Kubernetes workload clusters much more quickly.

When Kubernetes starts or recovers a node, each node must pull each copy of the workload image from a nearby registry, be it cloud, public or individually self-hosted.

Spegel sets up a distributed registry across each node, so each unique container can be downloaded once and then copied to other nodes.

Introducing the technology in a FOSDEM talk earlier this month, the Spegel creator posted benchmarks showing that image retrieval times can be improved by 82%.

This approach also speeds workload startup times and reduces network traffic.

Stateless Cluster Local OCI Registry

Cloud native current bottleneck is distributing the workloads to the runtime.

But operations can be thwarted by rate limits of the image registry, or come to a halt entirely should a registry go offline. Or images can disappear, such as what happened with Red Hat‘s Quay recently.

“There is no point of having a cluster that can scale to 10,000 nodes if you can’t pull down the image for the application you actually run,” Laine told the audience.

If the image extremely large, just the network travel time can slow things down, doubly so for rate limits: Docker Hub, for instance, limits download speeds to 100MB/s for images.

Like BitTorrent, but for Containers

Laine recalled a meetup presentation from 2018 or so from a system administrator about how his organization worked through a Docker Hub outage during a dramatic increase of its own usership. Operations could not scale up because it depended on several critical images from the temporarily-offline Hub.

The sysadmin’s solution was to ssh into an old node, then exporting the images and then basically continuously copy the images to the new nodes as they came on line.

“It worked, even if it was a very dirty solution,” Laine said.

The workaround sparked an idea with Laine: “Why aren’t we always doing this?”

Thus began work on Spegel, an OCI-complaint read-only registry.

The implementation turned out to be surprisingly easy, according to Laine, who was also one of the core developers of Flux GitOps tool.

An image is actually a collection of multiple components. At the top level is an index of all the other included components. It references, in a JSON format, all the other layers with their digest or the cryptographic hash of the content itself.

The Linux Foundation‘s Open Container Interface (OCI) specifies how containers are structured. The OCI distribution spec describes how clients pull images from a registry, which is done layer by layer.

Spegel allows Kubernetes nodes to pull images from each other. If none of the nodes have the image, the requests falls back to the original registry.

👁 Image

One advantage that OCI’s containerd format provides is that it stores uncompressed images layers on disk. The file names are the hashes.

“This means Spegel can piggyback off of Containerd. It is not doing any type of storage. So the role of the registry is to serve as proxy. “There is no state at all,” he said.

Each node has an OCI registry, which looks first on the local host for the layer. If one is not found, Spegel intercepts the request and looks on other nodes for the requested layer. If one is found, it proxies the request.

Speqel has three components: the registry, a routing and discovery component, and an advertising mechanism.

“It’s a bit like BitTorrent,” he said. “It’s a bunch of clients advertising to other clients.”

The registry looks at all the content on disk and then advertises it in a distributed hash table. The software uses a Go implementation of the widely used Kademlia Distributed Hash Table. When a request comes in, Spegel simply looks it up on the hash table.

👁 Image

New Docker Rate Limits

Today, the majority of users of Spegel tend to be home lab enthusiasts who are hoping to avoid Docker Hub rate limiting, Laine said. Other uses can be in air-gapped deployments or running very large machine learning models, which would copied much more quickly if done locally.

On March 1, Docker Hub latest rate limits for pulling images from Docker Hub. The professional (paid) accounts no longer have rate limits for the number of image pulls, personal accounts will be limited to 100 pulls an hour (10 if unauthenticated).

Spegel’s Compatibility with cloud providers varies according to their adherence to the OCI specs. Spgel works great with the Amazon Kubernetes Service, somewhat with the Azure Kubernetes Service and thus far, not at all with the Google Kubernetes Engine.

It also works great with MiniKube. It’s actually embedded in SUSE’s K3s and RKE2 Kubernetes distributions.

Ultimately, Spegel may help us rethink how image distribution could work through the power of peer-to-peer sharing, which would benefit the hobbyist and largest at-scale Kubernetes users alike.

TNS Analyst Lawrence Hecht contributed to this post. NOTE: The post was updated on February 24 to reflect revised Docker Hub rate limits. 

TRENDING STORIES
Joab Jackson is a senior editor for The New Stack, covering cloud native computing and system operations. He has reported on IT infrastructure and development for over 30 years, including stints at IDG and Government Computer News. Before that, he...
Read more from Joab Jackson
SHARE THIS STORY
TRENDING STORIES
Amazon Web Services, Docker, Google and Red Hat are sponsors of The New Stack. 
TNS owner Insight Partners is an investor in: Docker.
SHARE THIS STORY
TRENDING STORIES
TNS DAILY NEWSLETTER Receive a free roundup of the most recent TNS articles in your inbox each day.
The New Stack does not sell your information or share it with unaffiliated third parties. By continuing, you agree to our Terms of Use and Privacy Policy.