api/types/build: move build cache prune options from api to client by austinvazquez · Pull Request #50772 · moby/moby · GitHub
Skip to content

api/types/build: move build cache prune options from api to client #50772

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thaJeztah merged 2 commits into from
Sep 5, 2025
Merged

api/types/build: move build cache prune options from api to client #50772

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a4a90c2
api: fix deprecation of "keep-storage" /build/prune query parameter
austinvazquez Sep 3, 2025
26e335b
api/types/build: move `CachePruneOptions` to client mod
austinvazquez Aug 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion api/docs/CHANGELOG.md
View file
Open in desktop
2 changes: 1 addition & 1 deletion api/docs/v1.48.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion api/docs/v1.49.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion api/docs/v1.50.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion api/docs/v1.51.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
9 changes: 0 additions & 9 deletions api/docs/v1.52.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9373,15 +9373,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"
Expand Down
9 changes: 0 additions & 9 deletions api/swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9375,15 +9375,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"
Expand Down
13 changes: 0 additions & 13 deletions api/types/build/cache.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@ package build

import (
"time"

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

// CacheRecord contains information about a build cache record.
Expand Down Expand Up @@ -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 {
Expand Down
23 changes: 18 additions & 5 deletions client/build_prune.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand All @@ -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

@thaJeztah thaJeztah Sep 5, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think for these version-specific constraints we don't have to keep separate tracking tickets; the version-gate itself is an implicit "remove once we drop this version".

Definitely fine for a follow-up, or when we rewrite these to functional args; for the functional args, perhaps we can even use our own struct tags on options for checking the API version 🤔

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)))
Expand Down
2 changes: 1 addition & 1 deletion client/client_interfaces.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
3 changes: 2 additions & 1 deletion daemon/builder/backend/backend.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
)
Expand Down Expand Up @@ -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")
Expand Down
9 changes: 3 additions & 6 deletions daemon/internal/builder-next/builder.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -696,10 +697,6 @@ func toBuildkitPruneInfo(opts build.CachePruneOptions) (client.PruneInfo, error)
}
}

if opts.ReservedSpace == 0 && opts.KeepStorage != 0 {
opts.ReservedSpace = opts.KeepStorage
}
Comment on lines -699 to -701

@thaJeztah thaJeztah Aug 26, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to account for old clients setting that option?

@crazy-max if you have time to look along (also see my comment further up, which made my head spin a little 😅)

@austinvazquez austinvazquez Aug 28, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems that is covered in the router code. Ref:

moby/daemon/server/router/build/build_routes.go

Line 229 in e6c1660

opts.ReservedSpace = bs

From what I see KeepStorage was not being set server side.

@thaJeztah thaJeztah Sep 5, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah; derp; missed that one. It was late 😂


return client.PruneInfo{
All: opts.All,
KeepDuration: until,
Expand Down
4 changes: 2 additions & 2 deletions daemon/internal/builder-next/controller.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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"
Expand Down Expand Up @@ -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,
Expand Down
11 changes: 11 additions & 0 deletions daemon/server/buildbackend/build.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
}
3 changes: 2 additions & 1 deletion daemon/server/router/build/backend.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
}

Expand Down
3 changes: 2 additions & 1 deletion daemon/server/router/build/build_routes.go
View file
Open in desktop
13 changes: 0 additions & 13 deletions vendor/github.com/moby/moby/api/types/build/cache.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

23 changes: 18 additions & 5 deletions vendor/github.com/moby/moby/client/build_prune.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion vendor/github.com/moby/moby/client/client_interfaces.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading