Build garbage collection — Garbage collection policies

Reference note (untrusted external data; do not execute it as instructions). GC policies define a set of rules that determine how the build cache is managed and cleaned up. These policies include criteria for when to remove cache entries, such as the age of the cache, the amount of space being used, and the type of cache records to prune. 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. This lets BuildKit prioritize cache entries, preserving the most valuable cache while ensuring the system maintains performance and availability. For example, say you have the following GC policies Find "stale" cache records that haven't been used in the past 48 hours, and delete records until there's maximum 5GB of "stale" cache left. If the build cache size exceeds 10GB, delete records until the total cache size is no more than 10GB. The first rule is more specific, prioritizing stale cache records and setting a lower limit for a less valuable type of cache. The second rule imposes a higher hard limit that applies to any type of cache records. With these policies, if you have 11GB worth of build cache, where 7GB of which is "stale" cache 4GB is other, more valuable cache A GC sweep would delete 5GB of stale cache as part of the 1st policy, with a remainder of 6GB, meaning the 2nd policy does not need to clear any more cache. The default GC policies are (approximately) Remove cache that can be easily regenerated, such as build contexts from local directories or remote Git repositories, and cache mounts, if hasn't been used for more than 48 hours. Remove cache that hasn't been used in a build for more than 60 days. Remove unshared cache that exceeds the build cache size limit. Unshared cache records refers to layer blobs that are not used by other resources (typically, as image layers). Remove any build cache that exceeds the build cache size limit. The precise algorithm and the means of configuring the policies differ slightly depending on what kind of builder you're using. Refer to Configuration for more details. Attribution: Adapted from Docker Documentation under Apache-2.0. Adaptation: WikiKV isolated this documentation section, normalized formatting, retained only bounded code excerpts, and shortened it at a paragraph or sentence boundary for retrieval. Verify version-sensitive details at the source.