cache: rename new prune/gc control fields

Naming that was chosen during review was
reservedSpace, maxUsedSpace and minFreeSpace.

Signed-off-by: Tonis Tiigi <[email protected]>

Author: tonistiigi

api/services/control/control.pb.go

@@ -29,9 +29,9 @@ message PruneRequest {
 	bool all = 2;
 	int64 keepDuration = 3;
 
-	int64 minStorage = 4;
-	int64 maxStorage = 5;
-	int64 free = 6;
+	int64 reservedSpace = 4;
+	int64 maxUsedSpace = 5;
+	int64 minFreeSpace = 6;
 }
 
 message DiskUsageRequest {

api/services/control/control.proto

@@ -19,10 +19,10 @@ message GCPolicy {
 	int64 keepDuration = 2;
 	repeated string filters = 4;
 
-	// minStorage was renamed from freeBytes
-	int64 minStorage = 3;
-	int64 maxStorage = 5;
-	int64 free = 6;
+	// reservedSpace was renamed from freeBytes
+	int64 reservedSpace = 3;
+	int64 maxUsedSpace = 5;
+	int64 minFreeSpace = 6;
 }
 
 message BuildkitVersion {

api/types/worker.pb.go

@@ -1045,7 +1045,7 @@ func (cm *cacheManager) pruneOnce(ctx context.Context, ch chan client.UsageInfo,
 	}
 
 	totalSize := int64(0)
-	if opt.MaxStorage != 0 {
+	if opt.MaxUsedSpace != 0 {
 		du, err := cm.DiskUsage(ctx, client.DiskUsageInfo{})
 		if err != nil {
 			return err
@@ -1059,7 +1059,7 @@ func (cm *cacheManager) pruneOnce(ctx context.Context, ch chan client.UsageInfo,
 	}
 
 	var dstat disk.DiskStat
-	if opt.Free != 0 {
+	if opt.MinFreeSpace != 0 {
 		dstat, err = disk.GetDiskStat(cm.root)
 		if err != nil {
 			return err
@@ -1078,24 +1078,24 @@ func (cm *cacheManager) pruneOnce(ctx context.Context, ch chan client.UsageInfo,
 
 func calculateKeepBytes(totalSize int64, dstat disk.DiskStat, opt client.PruneInfo) int64 {
 	// 0 values are special, and means we have no keep cap
-	if opt.MaxStorage == 0 && opt.MinStorage == 0 && opt.Free == 0 {
+	if opt.MaxUsedSpace == 0 && opt.ReservedSpace == 0 && opt.MinFreeSpace == 0 {
 		return 0
 	}
 
 	// try and keep as many bytes as we can
-	keepBytes := opt.MaxStorage
+	keepBytes := opt.MaxUsedSpace
 
 	// if we need to free up space, then decrease to that
-	if excess := opt.Free - dstat.Free; excess > 0 {
+	if excess := opt.MinFreeSpace - dstat.Free; excess > 0 {
 		if keepBytes == 0 {
 			keepBytes = totalSize - excess
 		} else {
 			keepBytes = min(keepBytes, totalSize-excess)
 		}
 	}
 
-	// but make sure we don't take the total below the minimum
-	keepBytes = max(keepBytes, opt.MinStorage)
+	// but make sure we don't take the total below the reserved space
+	keepBytes = max(keepBytes, opt.ReservedSpace)
 
 	return keepBytes
 }

api/types/worker.proto

@@ -2480,7 +2480,7 @@ func TestCalculateKeepBytes(t *testing.T) {
 				Free:  9000,
 			},
 			opt: client.PruneInfo{
-				MaxStorage: 2000, // 20% of the disk
+				MaxUsedSpace: 2000, // 20% of the disk
 			},
 			result: 2000,
 		},
@@ -2492,7 +2492,7 @@ func TestCalculateKeepBytes(t *testing.T) {
 				Free:  3000,
 			},
 			opt: client.PruneInfo{
-				Free: 5000, // 50% of the disk
+				MinFreeSpace: 5000, // 50% of the disk
 			},
 			result: 5000,
 		},
@@ -2504,8 +2504,8 @@ func TestCalculateKeepBytes(t *testing.T) {
 				Free:  3000,
 			},
 			opt: client.PruneInfo{
-				Free:       5000, // 50% of the disk
-				MinStorage: 6000, // 60% of the disk,
+				MinFreeSpace:  5000, // 50% of the disk
+				ReservedSpace: 6000, // 60% of the disk,
 			},
 			result: 6000,
 		},
@@ -2517,9 +2517,9 @@ func TestCalculateKeepBytes(t *testing.T) {
 				Free:  3000,
 			},
 			opt: client.PruneInfo{
-				Free:       5000, // 50% of the disk
-				MinStorage: 2000, // 20% of the disk
-				MaxStorage: 4000, // 40% of the disk
+				MinFreeSpace:  5000, // 50% of the disk
+				ReservedSpace: 2000, // 20% of the disk
+				MaxUsedSpace:  4000, // 40% of the disk
 			},
 			result: 4000,
 		},
@@ -2531,7 +2531,7 @@ func TestCalculateKeepBytes(t *testing.T) {
 				Free:  2000, // something else is using 4000
 			},
 			opt: client.PruneInfo{
-				MaxStorage: 2000, // 20% of the disk
+				MaxUsedSpace: 2000, // 20% of the disk
 			},
 			result: 2000,
 		},
@@ -2543,7 +2543,7 @@ func TestCalculateKeepBytes(t *testing.T) {
 				Free:  2000, // something else is using 4000
 			},
 			opt: client.PruneInfo{
-				Free: 5000, // 50% of the disk
+				MinFreeSpace: 5000, // 50% of the disk
 			},
 			result: 1000,
 		},
@@ -2555,8 +2555,8 @@ func TestCalculateKeepBytes(t *testing.T) {
 				Free:  2000, // something else is using 4000
 			},
 			opt: client.PruneInfo{
-				Free:       5000, // 50% of the disk
-				MinStorage: 2000, // 20% of the disk
+				MinFreeSpace:  5000, // 50% of the disk
+				ReservedSpace: 2000, // 20% of the disk
 			},
 			result: 2000,
 		},
@@ -2568,9 +2568,9 @@ func TestCalculateKeepBytes(t *testing.T) {
 				Free:  2000, // something else is using 4000
 			},
 			opt: client.PruneInfo{
-				Free:       5000, // 50% of the disk
-				MinStorage: 2000, // 20% of the disk
-				MaxStorage: 4000, // 40% of the disk
+				MinFreeSpace:  5000, // 50% of the disk
+				ReservedSpace: 2000, // 20% of the disk
+				MaxUsedSpace:  4000, // 40% of the disk
 			},
 			result: 2000,
 		},

cache/manager.go

@@ -16,11 +16,11 @@ func (c *Client) Prune(ctx context.Context, ch chan UsageInfo, opts ...PruneOpti
 	}
 
 	req := &controlapi.PruneRequest{
-		Filter:       info.Filter,
-		KeepDuration: int64(info.KeepDuration),
-		MinStorage:   int64(info.MinStorage),
-		MaxStorage:   int64(info.MaxStorage),
-		Free:         int64(info.Free),
+		Filter:        info.Filter,
+		KeepDuration:  int64(info.KeepDuration),
+		ReservedSpace: int64(info.ReservedSpace),
+		MaxUsedSpace:  int64(info.MaxUsedSpace),
+		MinFreeSpace:  int64(info.MinFreeSpace),
 	}
 	if info.All {
 		req.All = true
@@ -71,9 +71,9 @@ type PruneInfo struct {
 	Filter       []string      `json:"filter"`
 	KeepDuration time.Duration `json:"keepDuration"`
 
-	MinStorage int64 `json:"minStorage"`
-	MaxStorage int64 `json:"maxStorage"`
-	Free       int64 `json:"free"`
+	ReservedSpace int64 `json:"reservedSpace"`
+	MaxUsedSpace  int64 `json:"maxUsedSpace"`
+	MinFreeSpace  int64 `json:"minFreeSpace"`
 }
 
 type pruneOptionFunc func(*PruneInfo)
@@ -86,11 +86,11 @@ var PruneAll = pruneOptionFunc(func(pi *PruneInfo) {
 	pi.All = true
 })
 
-func WithKeepOpt(duration time.Duration, minStorage int64, maxStorage int64, free int64) PruneOption {
+func WithKeepOpt(duration time.Duration, reserved int64, max int64, free int64) PruneOption {
 	return pruneOptionFunc(func(pi *PruneInfo) {
 		pi.KeepDuration = duration
-		pi.MinStorage = minStorage
-		pi.MaxStorage = maxStorage
-		pi.Free = free
+		pi.ReservedSpace = reserved
+		pi.MaxUsedSpace = max
+		pi.MinFreeSpace = free
 	})
 }

cache/manager_test.go

@@ -62,12 +62,12 @@ func fromAPIGCPolicy(in []*apitypes.GCPolicy) []PruneInfo {
 	out := make([]PruneInfo, 0, len(in))
 	for _, p := range in {
 		out = append(out, PruneInfo{
-			All:          p.All,
-			Filter:       p.Filters,
-			KeepDuration: time.Duration(p.KeepDuration),
-			MinStorage:   p.MinStorage,
-			MaxStorage:   p.MaxStorage,
-			Free:         p.Free,
+			All:           p.All,
+			Filter:        p.Filters,
+			KeepDuration:  time.Duration(p.KeepDuration),
+			ReservedSpace: p.ReservedSpace,
+			MaxUsedSpace:  p.MaxUsedSpace,
+			MinFreeSpace:  p.MinFreeSpace,
 		})
 	}
 	return out

client/prune.go

@@ -91,14 +91,14 @@ func printWorkersVerbose(tw *tabwriter.Writer, winfo []*client.WorkerInfo) {
 			if rule.KeepDuration > 0 {
 				fmt.Fprintf(tw, "\tKeep duration:\t%v\n", rule.KeepDuration.String())
 			}
-			if rule.MinStorage > 0 {
-				fmt.Fprintf(tw, "\tReserved storage:\t%g\n", units.Bytes(rule.MinStorage))
+			if rule.ReservedSpace > 0 {
+				fmt.Fprintf(tw, "\tReserved space:\t%g\n", units.Bytes(rule.ReservedSpace))
 			}
-			if rule.Free > 0 {
-				fmt.Fprintf(tw, "\tMaintain free storage:\t%g\n", units.Bytes(rule.Free))
+			if rule.MinFreeSpace > 0 {
+				fmt.Fprintf(tw, "\tMinimum free space:\t%g\n", units.Bytes(rule.MinFreeSpace))
 			}
-			if rule.MaxStorage > 0 {
-				fmt.Fprintf(tw, "\tMaximum storage:\t%g\n", units.Bytes(rule.MaxStorage))
+			if rule.MaxUsedSpace > 0 {
+				fmt.Fprintf(tw, "\tMaximum used space:\t%g\n", units.Bytes(rule.MaxUsedSpace))
 			}
 		}
 		fmt.Fprintf(tw, "\n")

client/workers.go

@@ -76,12 +76,12 @@ type OTELConfig struct {
 
 type GCConfig struct {
 	GC *bool `toml:"gc"`
-	// Deprecated: use GCMinStorage instead
-	GCKeepStorage DiskSpace  `toml:"gckeepstorage"`
-	GCMaxStorage  DiskSpace  `toml:"gcmaxstorage"`
-	GCMinStorage  DiskSpace  `toml:"gcminstorage"`
-	GCFreeStorage DiskSpace  `toml:"gcfreestorage"`
-	GCPolicy      []GCPolicy `toml:"gcpolicy"`
+	// Deprecated: use GCReservedSpace instead
+	GCKeepStorage   DiskSpace  `toml:"gckeepstorage"`
+	GCReservedSpace DiskSpace  `toml:"reservedSpace"`
+	GCMaxUsedSpace  DiskSpace  `toml:"maxUsedSpace"`
+	GCMinFreeSpace  DiskSpace  `toml:"minFreeSpace"`
+	GCPolicy        []GCPolicy `toml:"gcpolicy"`
 }
 
 type NetworkConfig struct {
@@ -167,20 +167,20 @@ type GCPolicy struct {
 	// to consume. Any storage above this mark can be cleared during a gc
 	// sweep.
 	//
-	// Deprecated: use MaxStorage instead
+	// Deprecated: use ReservedSpace instead
 	KeepBytes DiskSpace `toml:"keepBytes"`
 
-	// MinStorage is the minimum amount of storage this policy is always
-	// allowed to consume. Any amount of storage below this mark will not be
-	// cleared by this policy.
-	MinStorage DiskSpace `toml:"minStorage"`
-	// MaxStorage is the maximum amount of storage this policy is ever allowed
-	// to consume. Any storage above this mark can be cleared during a gc
-	// sweep.
-	MaxStorage DiskSpace `toml:"maxStorage"`
-	// Free is the amount of storage the gc will attempt to leave free on the
-	// disk. However, it will never attempt to bring it below MinStorage.
-	Free DiskSpace `toml:"free"`
+	// ReservedSpace is the minimum amount of disk space this policy is guaranteed to retain.
+	// Any usage below this threshold will not be reclaimed during garbage collection.
+	ReservedSpace DiskSpace `toml:"reservedSpace"`
+
+	// MaxUsedSpace is the maximum amount of disk space this policy is allowed to use.
+	// Any usage exceeding this limit will be cleaned up during a garbage collection sweep.
+	MaxUsedSpace DiskSpace `toml:"maxUsedSpace"`
+
+	// MinFreeSpace is the target amount of free disk space the garbage collector will attempt to leave.
+	// However, it will never let the available space fall below ReservedSpace.
+	MinFreeSpace DiskSpace `toml:"minFreeSpace"`
 }
 
 type DNSConfig struct {