Pull-Through Cache

Introduction
Docker Hub, Quay, and other registry providers all have pull limits, and costs associated with running them. Running large builds (or many small builds, frequently) may incur excess costs, rate limiting, or both. This guide will help you set up your own "pull-through" cache to optimize traffic, and bypass the limitations imposed by registry providers.
What Is A Pull Through Cache?
A pull through cache is a registry mirror that contains no images. When your client checks the registry for an image, the registry will either:
Give an existing response from its cache; thereby avoiding egress (or a pull) from your registry,
Or pull the image and its metadata from the registry on your behalf; caching it for later use.
Running A Pull-Through Cache
To run a cache, you'll need the ability to deploy a persistent service, somewhere. This could be a dedicated instance with Docker installed, or a container in your Kubernetes cluster. While we won't be giving details for how to set up either of these ways to run a service, we will be sharing configuration and usage details, and how you can use it with Earthly.
Docker has a guide for getting a pull-through cache up and running, and good documentation of the available options. Check out the registry image (and details).
Configuration & Tips
Set Up Mirror Authentication
Pull-through caches run unsecured by default. Add an htpasswd file for basic authentication, at a minimum:
1
auth:
2
  htpasswd:
3
    realm: basic-realm
4
    path: /auth/htpasswd
Copied!
Set Up Mirror TLS
Adding TLS is also highly recommended. you can bring your own certificates, or use the built-in LetsEncrypt support:
1
http:
2
  tls:
3
    letsencrypt:
4
      cachefile: /certs/cachefile
5
      email: [email protected]
6
      hosts: [my.cool.mirror.horse]
Copied!
The currently shipping library/registry image does not support the DNS-01 challenge yet, and some of the LetsEncrypt challenge support is getting out of date. If you need this, there is a tracking issue; We have had success by building the binary ourselves and replacing it in the image that Docker ships.
Use An Insecure Mirror
By default, Earthly expects your mirror to be using TLS. While this is not recommended, you can use an unsecured mirror by specifying the following config in the buildkit_additional_config setting:
1
global:
2
  buildkit_additional_config: |
3
    [registry."<upstream>"]
4
      mirrors = ["<mirror>"]
5
​
6
    [registry."<mirror>"]
7
      http = true
8
      insecure = true
Copied!
Where <mirror> is the host/port of your mirror, and <upstream> is the address of the registry you are intending to mirror.

CI Integration - Previous

Build An Earthly CI Image

Next - CI Integration

Remote BuildKit

Last modified 1mo ago

Copy link

Contents

Introduction

What Is A Pull Through Cache?

Running A Pull-Through Cache

Configuration & Tips