Home • Explore • Blog • CI
☰



docker
3rd chunk of `content/manuals/build/cache/garbage-collection.md`
316eff08337adba184fef951a55f4a7b64ca8ec01e853bbf0000000100000b9e
3. Remove any cache entries if build cache exceeds 100GB.

```json
{
  "builder": {
    "gc": {
      "enabled": true,
      "defaultKeepStorage": "50GB",
      "policy": [
        { "keepStorage": "0", "filter": ["unused-for=1440h"] },
        { "keepStorage": "0" },
        { "keepStorage": "100GB", "all": true }
      ]
    }
  }
}
```

Policies 1 and 2 here set `keepStorage` to `0`, which means they'll fall back
to the default limit of 50GB as defined by `defaultKeepStorage`.

### BuildKit configuration file

For build drivers other than `docker`, GC is configured using a
[`buildkitd.toml`](../buildkit/toml-configuration.md) configuration file. This
file uses the following high-level configuration options that you can use to
tweak the thresholds for how much disk space BuildKit should use for cache:

| Option          | Description                                                                                                                                             | Default value                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `reservedSpace` | The minimum amount of disk space BuildKit is allowed to allocate for cache. Usage below this threshold will not be reclaimed during garbage collection. | 10% of total disk space or 10GB (whichever is lower)  |
| `maxUsedSpace`  | The maximum amount of disk space that BuildKit is allowed to use. Usage above this threshold will be reclaimed during garbage collection.               | 60% of total disk space or 100GB (whichever is lower) |
| `minFreeSpace`  | The amount of disk space that must be kept free.                                                                                                        | 20GB                                                  |

You can set these options either as number of bytes, a unit string (for
example, `512MB`), or as a percentage of the total disk size. Changing these
options influences the default GC policies used by the BuildKit worker. With
the default thresholds, the GC policies resolve as follows:

```toml
# Global defaults
[worker.oci]
  gc = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"
  minFreeSpace = "20%"

# Policy 1
[[worker.oci.gcpolicy]]
  filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout" ]
  keepDuration = "48h"
  maxUsedSpace = "512MB"

# Policy 2
[[worker.oci.gcpolicy]]
  keepDuration = "1440h" # 60 days
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

# Policy 3
[[worker.oci.gcpolicy]]
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

# Policy 4
[[worker.oci.gcpolicy]]
  all = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"
```

In practical terms, this means:

- Policy 1: If the build cache exceeds 512MB, BuildKit removes cache records
Title: Configuring Garbage Collection with BuildKit configuration file
Summary
For build drivers other than Docker, GC is configured using a `buildkitd.toml` configuration file. The file provides high-level configuration options such as `reservedSpace`, `maxUsedSpace`, and `minFreeSpace` to control the amount of disk space BuildKit uses for cache. These options can be set as bytes, unit strings, or percentages of the total disk size. The document then presents the default GC policies based on these thresholds in `toml` format, outlining four policies that dictate how BuildKit removes cache records to manage disk space.