Find more intuitive name for `prune --keep-storage`

[tiborvass]

It seems like some users can be confused by the term keep-storage and misunderstood it as meaning the amount of free storage to keep, aka leave behind on the disk, instead of the maximum amount of cache that can be used up for cache by BuildKit.

Help output can be improved of course, but I find it also important to keep things as intuitive as possible and am open to deprecating and renaming the flag. Open to suggestions. The corresponding keepStorage name in GC policies would also need to be updated accordingly, which means the new name should also make sense in the context of a GC policy.

So far candidates are:

• --max-cache-storage
• --max-storage
• --max-cache
• --storage-limit

[mrmachine]

I just asked on Slack and couldn't find any examples (beyond the minimal "Amount of disk space to keep for cache" docs). This option is definitely not intuitive.

Even the suggested options don't really make sense to me, in the context of executing prune to empty the cache.

Is it actually a persistent setting to define once, and it will be remembered forevermore? What happens when the build cache exceeds the --max-cache-storage. Does it automatically prune old data?

What I want to do is prevent the cache from filling up my disk, but without having to prune EVERYTHING from the cache on a schedule (and causing a slow build while still needed cache data is repopulated immediately after the prune).

[evandrocoan]

What would the the unit? i.e., --keep-storage 50 means 50GB or MB of cache ?

[evandrocoan]

I just tested and this command docker builder prune --keep-storage 5000000 always cleans up all my caches. Shouldn't it accept a value and only clean up to that value?

[tmbull]

Agree with above comments. On CI servers, it would be nice to define a maximum size for the cache and then have oldest items automatically pruned. It's unclear if that's the purpose of this parameter or not.

[ouranos]

I agree that documentation on this feature is minimal. I found a bit more details in this comment: https://github.com/docker/buildx/issues/1065#issuecomment-1098357043 which seems to suggest it deletes "the oldest and least used cache first"

I tried the following on my machine:

➜ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          8         4         5.406GB   3.956GB (73%)
Containers      4         0         502.4kB   502.4kB (100%)
Local Volumes   9         4         8.848GB   85.96MB (0%)
Build Cache     865       0         20.74GB   20.74GB

➜ docker builder prune --keep-storage 10GB
WARNING! This will remove all dangling build cache. Are you sure you want to continue? [y/N] y
Deleted build cache objects:
rz3xtkhum253hz6es7lk151rv
...
fobb5ldg40vhzfkb673xxnpwm

Total reclaimed space: 10.85GB

➜ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          8         4         5.406GB   3.956GB (73%)
Containers      4         0         502.4kB   502.4kB (100%)
Local Volumes   9         4         8.848GB   85.96MB (0%)
Build Cache     452       0         9.89GB    9.89GB

I then rebuilt a recent image (that I deleted with docker rmi) and all the steps were cached so it seems to do what it says (not so clearly) on the tin 🙂

Agree with above comments. On CI servers, it would be nice to define a maximum size for the cache and then have oldest items automatically pruned. It's unclear if that's the purpose of this parameter or not.

So regularly running docker builder prune --keep-storage <max-size>GB would do the trick.

[chris-crunchr]

Just found this option and it looks promising, if its clear how it works! While it works, I'm not sure how it decides what stays and what goes. :thinking:

Also, it seems to go for dangling cache, but I'm not sure what this means in this context. Are these only layers that are not part of any current build? It seems to destroy caches that were used seconds ago, which makes me wonder what stays..