@@ -97,6 +97,8 @@ keywords: "API, Docker, rcli, REST, documentation"

   `GET /info` response are now always be `false` and will be omitted in API

   v1.49. The netfilter module is now loaded on-demand, and no longer during

   daemon startup, making these fields obsolete.

+* Deprecated: The `POST /build/prune` `keep-storage` query parameter has been

+  renamed to `reserved-space`. `keep-storage` support will be removed in API v1.52.

 * `GET /images/{name}/history` now supports a `platform` parameter (JSON

   encoded OCI Platform type) that allows to specify a platform to show the

   history of.

@@ -151,7 +153,7 @@ keywords: "API, Docker, rcli, REST, documentation"

   `GET /debug/pprof/profile`, `GET /debug/pprof/symbol`, `GET /debug/pprof/trace`,

   `GET /debug/pprof/{name}`) are now also accessible through the versioned-API

   paths (`/v<API-version>/<endpoint>`).

-* `POST /build/prune` renames `keep-bytes` to `reserved-space` and now supports

+* `POST /build/prune` renames `keep-storage` to `reserved-space` and now supports

   additional prune parameters `max-used-space` and `min-free-space`.

 * `GET /containers/json` now returns an `ImageManifestDescriptor` field

   matching the same field in `/containers/{name}/json`.

@@ -9509,7 +9509,7 @@ paths:

             Amount of disk space in bytes to keep for cache

             > **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space".

-            > It is kept for backward compatibility and will be removed in API v1.49.

+            > It is kept for backward compatibility and will be removed in API v1.52.

           type: "integer"

           format: "int64"

         - name: "reserved-space"

@@ -9509,7 +9509,7 @@ paths:

             Amount of disk space in bytes to keep for cache

             > **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space".

-            > It is kept for backward compatibility and will be removed in API v1.49.

+            > It is kept for backward compatibility and will be removed in API v1.52.

           type: "integer"

           format: "int64"

         - name: "reserved-space"

@@ -9393,7 +9393,7 @@ paths:

             Amount of disk space in bytes to keep for cache

             > **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space".

-            > It is kept for backward compatibility and will be removed in API v1.49.

+            > It is kept for backward compatibility and will be removed in API v1.52.

           type: "integer"

           format: "int64"

         - name: "reserved-space"

@@ -9394,7 +9394,7 @@ paths:

             Amount of disk space in bytes to keep for cache

             > **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space".

-            > It is kept for backward compatibility and will be removed in API v1.49.

+            > It is kept for backward compatibility and will be removed in API v1.52.

           type: "integer"

           format: "int64"

         - name: "reserved-space"

@@ -9376,15 +9376,6 @@ paths:

         - "application/json"

       operationId: "BuildPrune"

       parameters:

-        - name: "keep-storage"

-          in: "query"

-          description: |

-            Amount of disk space in bytes to keep for cache

-

-            > **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space".

-            > It is kept for backward compatibility and will be removed in API v1.49.

-          type: "integer"

-          format: "int64"

         - name: "reserved-space"

           in: "query"

           description: "Amount of disk space in bytes to keep for cache"

@@ -9376,15 +9376,6 @@ paths:

         - "application/json"

       operationId: "BuildPrune"

       parameters:

-        - name: "keep-storage"

-          in: "query"

-          description: |

-            Amount of disk space in bytes to keep for cache

-

-            > **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space".

-            > It is kept for backward compatibility and will be removed in API v1.49.

-          type: "integer"

-          format: "int64"

         - name: "reserved-space"

           in: "query"

           description: "Amount of disk space in bytes to keep for cache"

@@ -2,8 +2,6 @@ package build

 import (

 	"time"

-

-	"github.com/moby/moby/api/types/filters"

 )

 // CacheRecord contains information about a build cache record.

@@ -33,17 +31,6 @@ type CacheRecord struct {

 	UsageCount int

 }

-// CachePruneOptions hold parameters to prune the build cache.

-type CachePruneOptions struct {

-	All           bool

-	ReservedSpace int64

-	MaxUsedSpace  int64

-	MinFreeSpace  int64

-	Filters       filters.Args

-

-	KeepStorage int64 // Deprecated: deprecated in API 1.48.

-}

-

 // CachePruneReport contains the response for Engine API:

 // POST "/build/prune"

 type CachePruneReport struct {

@@ -9,10 +9,20 @@ import (

 	"github.com/moby/moby/api/types/build"

 	"github.com/moby/moby/api/types/filters"

+	"github.com/moby/moby/api/types/versions"

 )

+// BuildCachePruneOptions hold parameters to prune the build cache.

+type BuildCachePruneOptions struct {

+	All           bool

+	ReservedSpace int64

+	MaxUsedSpace  int64

+	MinFreeSpace  int64

+	Filters       filters.Args

+}

+

 // BuildCachePrune requests the daemon to delete unused cache data.

-func (cli *Client) BuildCachePrune(ctx context.Context, opts build.CachePruneOptions) (*build.CachePruneReport, error) {

+func (cli *Client) BuildCachePrune(ctx context.Context, opts BuildCachePruneOptions) (*build.CachePruneReport, error) {

 	if err := cli.NewVersionError(ctx, "1.31", "build prune"); err != nil {

 		return nil, err

 	}

@@ -22,11 +32,14 @@ func (cli *Client) BuildCachePrune(ctx context.Context, opts build.CachePruneOpt

 		query.Set("all", "1")

 	}

-	if opts.KeepStorage != 0 {

-		query.Set("keep-storage", strconv.Itoa(int(opts.KeepStorage)))

-	}

 	if opts.ReservedSpace != 0 {

-		query.Set("reserved-space", strconv.Itoa(int(opts.ReservedSpace)))

+		// Prior to API v1.48, 'keep-storage' was used to set the reserved space for the build cache.

+		// TODO(austinvazquez): remove once API v1.47 is no longer supported. See https://github.com/moby/moby/issues/50902

+		if versions.LessThanOrEqualTo(cli.version, "1.47") {

+			query.Set("keep-storage", strconv.Itoa(int(opts.ReservedSpace)))

+		} else {

+			query.Set("reserved-space", strconv.Itoa(int(opts.ReservedSpace)))

+		}

 	}

 	if opts.MaxUsedSpace != 0 {

 		query.Set("max-used-space", strconv.Itoa(int(opts.MaxUsedSpace)))

@@ -107,7 +107,7 @@ type DistributionAPIClient interface {

 // ImageAPIClient defines API client methods for the images

 type ImageAPIClient interface {

 	ImageBuild(ctx context.Context, context io.Reader, options build.ImageBuildOptions) (build.ImageBuildResponse, error)

-	BuildCachePrune(ctx context.Context, opts build.CachePruneOptions) (*build.CachePruneReport, error)

+	BuildCachePrune(ctx context.Context, opts BuildCachePruneOptions) (*build.CachePruneReport, error)

 	BuildCancel(ctx context.Context, id string) error

 	ImageCreate(ctx context.Context, parentReference string, options ImageCreateOptions) (io.ReadCloser, error)

 	ImageImport(ctx context.Context, source ImageImportSource, ref string, options ImageImportOptions) (io.ReadCloser, error)

@@ -14,6 +14,7 @@ import (

 	"github.com/moby/moby/v2/daemon/internal/image"

 	"github.com/moby/moby/v2/daemon/internal/stringid"

 	"github.com/moby/moby/v2/daemon/server/backend"

+	"github.com/moby/moby/v2/daemon/server/buildbackend"

 	"github.com/pkg/errors"

 	"google.golang.org/grpc"

 )

@@ -97,7 +98,7 @@ func (b *Backend) Build(ctx context.Context, config backend.BuildConfig) (string

 }

 // PruneCache removes all cached build sources

-func (b *Backend) PruneCache(ctx context.Context, opts build.CachePruneOptions) (*build.CachePruneReport, error) {

+func (b *Backend) PruneCache(ctx context.Context, opts buildbackend.CachePruneOptions) (*build.CachePruneReport, error) {

 	buildCacheSize, cacheIDs, err := b.buildkit.Prune(ctx, opts)

 	if err != nil {

 		return nil, errors.Wrap(err, "failed to prune build cache")

@@ -33,6 +33,7 @@ import (

 	"github.com/moby/moby/v2/daemon/libnetwork"

 	"github.com/moby/moby/v2/daemon/pkg/opts"

 	"github.com/moby/moby/v2/daemon/server/backend"

+	"github.com/moby/moby/v2/daemon/server/buildbackend"

 	"github.com/moby/moby/v2/errdefs"

 	"github.com/moby/sys/user"

 	"github.com/pkg/errors"

@@ -187,7 +188,7 @@ func (b *Builder) DiskUsage(ctx context.Context) ([]*build.CacheRecord, error) {

 }

 // Prune clears all reclaimable build cache.

-func (b *Builder) Prune(ctx context.Context, opts build.CachePruneOptions) (int64, []string, error) {

+func (b *Builder) Prune(ctx context.Context, opts buildbackend.CachePruneOptions) (int64, []string, error) {

 	ch := make(chan *controlapi.UsageRecord)

 	eg, ctx := errgroup.WithContext(ctx)

@@ -641,7 +642,7 @@ func toBuildkitUlimits(inp []*container.Ulimit) (string, error) {

 	return strings.Join(ulimits, ","), nil

 }

-func toBuildkitPruneInfo(opts build.CachePruneOptions) (client.PruneInfo, error) {

+func toBuildkitPruneInfo(opts buildbackend.CachePruneOptions) (client.PruneInfo, error) {

 	var until time.Duration

 	untilValues := opts.Filters.Get("until")          // canonical

 	unusedForValues := opts.Filters.Get("unused-for") // deprecated synonym for "until" filter

@@ -696,10 +697,6 @@ func toBuildkitPruneInfo(opts build.CachePruneOptions) (client.PruneInfo, error)

 		}

 	}

-	if opts.ReservedSpace == 0 && opts.KeepStorage != 0 {

-		opts.ReservedSpace = opts.KeepStorage

-	}

-

 	return client.PruneInfo{

 		All:           opts.All,

 		KeepDuration:  until,

@@ -45,7 +45,6 @@ import (

 	"github.com/moby/buildkit/worker"

 	"github.com/moby/buildkit/worker/containerd"

 	"github.com/moby/buildkit/worker/label"

-	"github.com/moby/moby/api/types/build"

 	"github.com/moby/moby/api/types/filters"

 	"github.com/moby/moby/v2/daemon/config"

 	"github.com/moby/moby/v2/daemon/graphdriver"

@@ -56,6 +55,7 @@ import (

 	"github.com/moby/moby/v2/daemon/internal/builder-next/imagerefchecker"

 	mobyworker "github.com/moby/moby/v2/daemon/internal/builder-next/worker"

 	wlabel "github.com/moby/moby/v2/daemon/internal/builder-next/worker/label"

+	"github.com/moby/moby/v2/daemon/server/buildbackend"

 	"github.com/pkg/errors"

 	bolt "go.etcd.io/bbolt"

 	"go.opentelemetry.io/otel/sdk/trace"

@@ -484,7 +484,7 @@ func getGCPolicy(conf config.BuilderConfig, root string) ([]client.PruneInfo, er

 					return nil, err

 				}

-				gcPolicy[i], err = toBuildkitPruneInfo(build.CachePruneOptions{

+				gcPolicy[i], err = toBuildkitPruneInfo(buildbackend.CachePruneOptions{

 					All:           p.All,

 					ReservedSpace: reservedSpace,

 					MaxUsedSpace:  maxUsedSpace,

new file mode 100644

@@ -0,0 +1,11 @@

+package buildbackend

+

+import "github.com/moby/moby/api/types/filters"

+

+type CachePruneOptions struct {

+	All           bool

+	ReservedSpace int64

+	MaxUsedSpace  int64

+	MinFreeSpace  int64

+	Filters       filters.Args

+}

@@ -5,6 +5,7 @@ import (

 	"github.com/moby/moby/api/types/build"

 	"github.com/moby/moby/v2/daemon/server/backend"

+	"github.com/moby/moby/v2/daemon/server/buildbackend"

 )

 // Backend abstracts an image builder whose only purpose is to build an image referenced by an imageID.

@@ -14,7 +15,7 @@ type Backend interface {

 	Build(context.Context, backend.BuildConfig) (string, error)

 	// PruneCache prunes the build cache.

-	PruneCache(context.Context, build.CachePruneOptions) (*build.CachePruneReport, error)

+	PruneCache(context.Context, buildbackend.CachePruneOptions) (*build.CachePruneReport, error)

 	Cancel(context.Context, string) error

 }

@@ -24,6 +24,7 @@ import (

 	"github.com/moby/moby/api/types/registry"

 	"github.com/moby/moby/api/types/versions"

 	"github.com/moby/moby/v2/daemon/server/backend"

+	"github.com/moby/moby/v2/daemon/server/buildbackend"

 	"github.com/moby/moby/v2/daemon/server/httputils"

 	"github.com/moby/moby/v2/pkg/ioutils"

 	"github.com/pkg/errors"

@@ -179,7 +180,7 @@ func (br *buildRouter) postPrune(ctx context.Context, w http.ResponseWriter, r *

 		return err

 	}

-	opts := build.CachePruneOptions{

+	opts := buildbackend.CachePruneOptions{

 		All:     httputils.BoolValue(r, "all"),

 		Filters: fltrs,

 	}

@@ -2,8 +2,6 @@ package build

 import (

 	"time"

-

-	"github.com/moby/moby/api/types/filters"

 )

 // CacheRecord contains information about a build cache record.

@@ -33,17 +31,6 @@ type CacheRecord struct {

 	UsageCount int

 }

-// CachePruneOptions hold parameters to prune the build cache.

-type CachePruneOptions struct {

-	All           bool

-	ReservedSpace int64

-	MaxUsedSpace  int64

-	MinFreeSpace  int64

-	Filters       filters.Args

-

-	KeepStorage int64 // Deprecated: deprecated in API 1.48.

-}

-

 // CachePruneReport contains the response for Engine API:

 // POST "/build/prune"

 type CachePruneReport struct {

@@ -9,10 +9,20 @@ import (

 	"github.com/moby/moby/api/types/build"

 	"github.com/moby/moby/api/types/filters"

+	"github.com/moby/moby/api/types/versions"

 )

+// BuildCachePruneOptions hold parameters to prune the build cache.

+type BuildCachePruneOptions struct {

+	All           bool

+	ReservedSpace int64

+	MaxUsedSpace  int64

+	MinFreeSpace  int64

+	Filters       filters.Args

+}

+

 // BuildCachePrune requests the daemon to delete unused cache data.

-func (cli *Client) BuildCachePrune(ctx context.Context, opts build.CachePruneOptions) (*build.CachePruneReport, error) {

+func (cli *Client) BuildCachePrune(ctx context.Context, opts BuildCachePruneOptions) (*build.CachePruneReport, error) {

 	if err := cli.NewVersionError(ctx, "1.31", "build prune"); err != nil {

 		return nil, err

 	}

@@ -22,11 +32,14 @@ func (cli *Client) BuildCachePrune(ctx context.Context, opts build.CachePruneOpt

 		query.Set("all", "1")

 	}

-	if opts.KeepStorage != 0 {

-		query.Set("keep-storage", strconv.Itoa(int(opts.KeepStorage)))

-	}

 	if opts.ReservedSpace != 0 {

-		query.Set("reserved-space", strconv.Itoa(int(opts.ReservedSpace)))

+		// Prior to API v1.48, 'keep-storage' was used to set the reserved space for the build cache.

+		// TODO(austinvazquez): remove once API v1.47 is no longer supported. See https://github.com/moby/moby/issues/50902

+		if versions.LessThanOrEqualTo(cli.version, "1.47") {

+			query.Set("keep-storage", strconv.Itoa(int(opts.ReservedSpace)))

+		} else {

+			query.Set("reserved-space", strconv.Itoa(int(opts.ReservedSpace)))

+		}

 	}

 	if opts.MaxUsedSpace != 0 {

 		query.Set("max-used-space", strconv.Itoa(int(opts.MaxUsedSpace)))

@@ -107,7 +107,7 @@ type DistributionAPIClient interface {

 // ImageAPIClient defines API client methods for the images

 type ImageAPIClient interface {

 	ImageBuild(ctx context.Context, context io.Reader, options build.ImageBuildOptions) (build.ImageBuildResponse, error)

-	BuildCachePrune(ctx context.Context, opts build.CachePruneOptions) (*build.CachePruneReport, error)

+	BuildCachePrune(ctx context.Context, opts BuildCachePruneOptions) (*build.CachePruneReport, error)

 	BuildCancel(ctx context.Context, id string) error

 	ImageCreate(ctx context.Context, parentReference string, options ImageCreateOptions) (io.ReadCloser, error)

 	ImageImport(ctx context.Context, source ImageImportSource, ref string, options ImageImportOptions) (io.ReadCloser, error)