Quartz 5

Docker Build Garbage Collection

Properties1
tagsreference, infrastructure, container

2 min read

Summary

Docker BuildKit’s garbage collection (GC) manages build cache automatically by applying a sequence of increasingly broad prune policies when cache exceeds size or age thresholds. For the default docker driver, GC is configured via daemon.json; for custom BuildKit runners, it uses buildkitd.toml. The key parameters are reservedSpace (minimum kept), maxUsedSpace (triggers pruning), and minFreeSpace (disk headroom).

Docker BuildKit 透過有序的 GC 策略自動清理建置快取，從最具體（過期暫時快取）到最廣泛（所有快取）依序執行。可透過 daemon.json 或 buildkitd.toml 設定空間上下限，適合需要精細控制快取行為的大型建置環境。

Key Points

  • GC policies execute sequentially from most-specific to least-specific; each policy only triggers if the previous didn’t free enough space
  • Default Docker driver has four built-in policies: (1) ephemeral stale >48h, (2) unused >60 days, (3) unshared over limit, (4) all over limit
  • reservedSpace always takes priority — cache never shrinks below this floor even if other thresholds demand it
  • daemon.json uses single = in filters; buildkitd.toml uses == — common source of config errors
  • all: true policy is the nuclear option: prunes shared/internal records too; use only as a last-resort policy
  • Percentage-based sizes (e.g., "20%") are supported and recommended for portable configs

Insights

The layered policy design mirrors garbage collection in memory management: generational collection where short-lived, easily-regenerated cache (local contexts, Git checkouts, cache mounts) is pruned first at a lower threshold, preserving the expensive shared layer blobs until truly necessary. This is the right mental model for tuning: treat the policies as tiers of value, not independent rules.

For CI/CD self-hosted runners with constrained SSDs, setting minFreeSpace as a percentage prevents CI failures from disk exhaustion better than absolute sizes, since disk capacity varies across runner fleet nodes.

Connections

Raw Excerpt

“Each GC policy is evaluated in sequence, starting with the most specific criteria, and proceeds to broader rules if previous policies do not free up enough cache.”

Graph View