Cache Backends

Cache Backends

Inline, Registry and Local Cache Backends

A builder's cache lives on its own disk, so a fresh CI agent or a new builder starts cold. --cache-to exports the cache and --cache-from imports it:

BuildKit 10,294 's cache backends
Backend	Where the cache goes	Typical use
inline	Inside the pushed image itself	Simple; final-stage layers only
registry	A separate tag in a registry	CI on many machines
local	A directory on disk	One machine, or a CI cache folder
gha	The GitHub Actions 29 cache service	Workflows (GitHub)
s3, azblob	Amazon S3 24 , Azure 6 Blob Storage	Self-hosted runners in the cloud

mode=min, the default, exports only the layers of the final image; mode=max also exports intermediate stages such as deps, which is what makes a multi-stage build fast on a cold machine. The default docker driver supports inline, local, registry and gha when it uses the containerd 234,762 image store, as Engine 29 does. Export BookNest's cache to the lab registry, wipe the builder completely, and build again from the imported cache:

Exporting the cache, pruning the builder and building from the registry cacheShell

CACHE=type=registry,ref=localhost:33500/l3-booknest-api:buildcache
docker buildx build -q --builder l3-builder -t localhost:33500/l3-booknest-api:ci \
  --push --cache-to $CACHE,mode=max . >/dev/null
docker buildx prune --builder l3-builder -af | tail -1
docker buildx build --builder l3-builder --progress=plain \
  -t localhost:33500/l3-booknest-api:ci --push --cache-from $CACHE . 2>&1 |
  grep -E '^#[0-9]+ (importing cache|CACHED)' | sed 's/^#[0-9]* //' | sort | uniq -c

Output

Total:  745.7MB
      7 CACHED
      1 importing cache manifest from localhost:33500/l3-booknest-api:buildcache

Every step, deps included (thanks to mode=max), came from the registry although the builder had just deleted its whole cache. --cache-from may be repeated, for example with the main branch's cache and the current branch's.

MENU