Skip to content

commands: make builder status timeouts configurable across cli flows #3665

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
crazy-max merged 1 commit into from
Feb 24, 2026
+97 −45
Merged

commands: make builder status timeouts configurable across cli flows #3665

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 5 additions & 2 deletions builder/builder.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,6 +346,7 @@ type CreateOpts struct {
Use bool
Endpoint string
Append bool
Timeout time.Duration
}

func Create(ctx context.Context, txn *store.Txn, dockerCli command.Cli, opts CreateOpts) (*Builder, error) {
Expand Down Expand Up @@ -525,8 +526,10 @@ func Create(ctx context.Context, txn *store.Txn, dockerCli command.Cli, opts Cre
return nil, err
}

cancelCtx, cancel := context.WithCancelCause(ctx)
timeoutCtx, _ := context.WithTimeoutCause(cancelCtx, 20*time.Second, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
timeoutCtx, cancel := context.WithCancelCause(ctx)
if opts.Timeout > 0 {
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, opts.Timeout, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
}
defer func() { cancel(errors.WithStack(context.Canceled)) }()

nodes, err := b.LoadNodes(timeoutCtx, WithData())
Expand Down
4 changes: 4 additions & 0 deletions commands/create.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"bytes"
"context"
"fmt"
"time"

"github.com/docker/buildx/builder"
"github.com/docker/buildx/driver"
Expand All @@ -27,6 +28,7 @@ type createOptions struct {
buildkitdFlags string
buildkitdConfigFile string
bootstrap bool
timeout time.Duration
// upgrade bool // perform upgrade of the driver
}

Expand Down Expand Up @@ -61,6 +63,7 @@ func runCreate(ctx context.Context, dockerCli command.Cli, in createOptions, arg
Use: in.use,
Endpoint: ep,
Append: in.actionAppend,
Timeout: in.timeout,
})
if err != nil {
return err
Expand Down Expand Up @@ -120,6 +123,7 @@ func createCmd(dockerCli command.Cli) *cobra.Command {
flags.BoolVar(&options.actionAppend, "append", false, "Append a node to builder instead of changing it")
flags.BoolVar(&options.actionLeave, "leave", false, "Remove a node from builder instead of changing it")
flags.BoolVar(&options.use, "use", false, "Set the current builder instance")
setBuilderStatusTimeoutFlag(flags, &options.timeout)

// hide builder persistent flag for this command
cobrautil.HideInheritedFlags(cmd, "builder")
Expand Down
10 changes: 9 additions & 1 deletion commands/diskusage.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ type duOptions struct {
filter opts.FilterOpt
verbose bool
format string
timeout time.Duration
}

func runDiskUsage(ctx context.Context, dockerCli command.Cli, opts duOptions) error {
Expand Down Expand Up @@ -92,7 +93,13 @@ func runDiskUsage(ctx context.Context, dockerCli command.Cli, opts duOptions) er
return err
}

nodes, err := b.LoadNodes(ctx)
timeoutCtx, cancel := context.WithCancelCause(ctx)
if opts.timeout > 0 {
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, opts.timeout, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
}
defer func() { cancel(errors.WithStack(context.Canceled)) }()

nodes, err := b.LoadNodes(timeoutCtx)
if err != nil {
return err
}
Expand Down Expand Up @@ -197,6 +204,7 @@ func duCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {
flags.Var(&options.filter, "filter", "Provide filter values")
flags.BoolVar(&options.verbose, "verbose", false, `Shorthand for "--format=pretty"`)
flags.StringVar(&options.format, "format", "", "Format the output")
setBuilderStatusTimeoutFlag(flags, &options.timeout)

return cmd
}
Expand Down
6 changes: 5 additions & 1 deletion commands/inspect.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import (
type inspectOptions struct {
bootstrap bool
builder string
timeout time.Duration
}

func runInspect(ctx context.Context, dockerCli command.Cli, in inspectOptions) error {
Expand All @@ -36,7 +37,9 @@ func runInspect(ctx context.Context, dockerCli command.Cli, in inspectOptions) e
}

timeoutCtx, cancel := context.WithCancelCause(ctx)
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, 20*time.Second, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
if in.timeout > 0 {
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, in.timeout, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
}
defer func() { cancel(errors.WithStack(context.Canceled)) }()

nodes, err := b.LoadNodes(timeoutCtx, builder.WithData())
Expand Down Expand Up @@ -188,6 +191,7 @@ func inspectCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {

flags := cmd.Flags()
flags.BoolVar(&options.bootstrap, "bootstrap", false, "Ensure builder has booted before inspecting")
setBuilderStatusTimeoutFlag(flags, &options.timeout)

return cmd
}
Expand Down
6 changes: 5 additions & 1 deletion commands/ls.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ const (
type lsOptions struct {
format string
noTrunc bool
timeout time.Duration
}

func runLs(ctx context.Context, dockerCli command.Cli, in lsOptions) error {
Expand All @@ -60,7 +61,9 @@ func runLs(ctx context.Context, dockerCli command.Cli, in lsOptions) error {
}

timeoutCtx, cancel := context.WithCancelCause(ctx)
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, 20*time.Second, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
if in.timeout > 0 {
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, in.timeout, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
}
defer func() { cancel(errors.WithStack(context.Canceled)) }()

eg, _ := errgroup.WithContext(timeoutCtx)
Expand Down Expand Up @@ -114,6 +117,7 @@ func lsCmd(dockerCli command.Cli) *cobra.Command {
flags := cmd.Flags()
flags.StringVar(&options.format, "format", formatter.TableFormatKey, "Format the output")
flags.BoolVar(&options.noTrunc, "no-trunc", false, "Don't truncate output")
setBuilderStatusTimeoutFlag(flags, &options.timeout)

// hide builder persistent flag for this command
cobrautil.HideInheritedFlags(cmd, "builder")
Expand Down
10 changes: 9 additions & 1 deletion commands/prune.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ type pruneOptions struct {
minFreeSpace opts.MemBytes
force bool
verbose bool
timeout time.Duration
}

const (
Expand Down Expand Up @@ -68,7 +69,13 @@ func runPrune(ctx context.Context, dockerCli command.Cli, opts pruneOptions) err
return err
}

nodes, err := b.LoadNodes(ctx)
timeoutCtx, cancel := context.WithCancelCause(ctx)
if opts.timeout > 0 {
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, opts.timeout, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
}
defer func() { cancel(errors.WithStack(context.Canceled)) }()

nodes, err := b.LoadNodes(timeoutCtx)
if err != nil {
return err
}
Expand Down Expand Up @@ -182,6 +189,7 @@ func pruneCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {
flags.Var(&options.maxUsedSpace, "max-used-space", "Maximum amount of disk space allowed to keep for cache")
flags.BoolVar(&options.verbose, "verbose", false, "Provide a more verbose output")
flags.BoolVarP(&options.force, "force", "f", false, "Do not prompt for confirmation")
setBuilderStatusTimeoutFlag(flags, &options.timeout)

flags.Var(&options.reservedSpace, "keep-storage", "Amount of disk space to keep for cache")
flags.MarkDeprecated("keep-storage", "keep-storage flag has been changed to reserved-space")
Expand Down
16 changes: 13 additions & 3 deletions commands/rm.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ type rmOptions struct {
keepDaemon bool
allInactive bool
force bool
timeout time.Duration
}

const (
Expand All @@ -46,7 +47,13 @@ func runRm(ctx context.Context, dockerCli command.Cli, in rmOptions) error {
return rmAllInactive(ctx, txn, dockerCli, in)
}

eg, _ := errgroup.WithContext(ctx)
timeoutCtx, cancel := context.WithCancelCause(ctx)
if in.timeout > 0 {
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, in.timeout, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
}
defer func() { cancel(errors.WithStack(context.Canceled)) }()

eg, _ := errgroup.WithContext(timeoutCtx)
for _, name := range in.builders {
func(name string) {
eg.Go(func() (err error) {
Expand All @@ -67,7 +74,7 @@ func runRm(ctx context.Context, dockerCli command.Cli, in rmOptions) error {
return err
}

nodes, err := b.LoadNodes(ctx)
nodes, err := b.LoadNodes(timeoutCtx)
if err != nil {
return err
}
Expand Down Expand Up @@ -120,6 +127,7 @@ func rmCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {
flags.BoolVar(&options.keepDaemon, "keep-daemon", false, "Keep the BuildKit daemon running")
flags.BoolVar(&options.allInactive, "all-inactive", false, "Remove all inactive builders")
flags.BoolVarP(&options.force, "force", "f", false, "Do not prompt for confirmation")
setBuilderStatusTimeoutFlag(flags, &options.timeout)

return cmd
}
Expand Down Expand Up @@ -152,7 +160,9 @@ func rmAllInactive(ctx context.Context, txn *store.Txn, dockerCli command.Cli, i
}

timeoutCtx, cancel := context.WithCancelCause(ctx)
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, 20*time.Second, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
if in.timeout > 0 {
timeoutCtx, _ = context.WithTimeoutCause(timeoutCtx, in.timeout, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent
}
defer func() { cancel(errors.WithStack(context.Canceled)) }()

eg, _ := errgroup.WithContext(timeoutCtx)
Expand Down
5 changes: 5 additions & 0 deletions commands/root.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package commands
import (
"fmt"
"os"
"time"

historycmd "github.com/docker/buildx/commands/history"
imagetoolscmd "github.com/docker/buildx/commands/imagetools"
Expand Down Expand Up @@ -142,3 +143,7 @@ func rootFlags(options *rootOptions, flags *pflag.FlagSet) {
flags.StringVar(&options.builder, "builder", os.Getenv("BUILDX_BUILDER"), "Override the configured builder instance")
flags.BoolVarP(&options.debug, "debug", "D", debug.IsEnabled(), "Enable debug logging")
}

func setBuilderStatusTimeoutFlag(flags *pflag.FlagSet, target *time.Duration) {
flags.DurationVar(target, "timeout", 20*time.Second, "Override the default timeout for loading builder status")
}
1 change: 1 addition & 0 deletions docs/reference/buildx_create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Create a new builder instance
| [`--name`](#name) | `string` | | Builder instance name |
| [`--node`](#node) | `string` | | Create/modify node with given name |
| [`--platform`](#platform) | `stringArray` | | Fixed platforms for current node |
| `--timeout` | `duration` | `20s` | Override the default timeout for loading builder status |
| [`--use`](#use) | `bool` | | Set the current builder instance |


Expand Down
15 changes: 8 additions & 7 deletions docs/reference/buildx_du.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,14 @@ Disk usage

### Options

| Name | Type | Default | Description |
|:------------------------|:---------|:--------|:-----------------------------------------|
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--filter`](#filter) | `filter` | | Provide filter values |
| [`--format`](#format) | `string` | | Format the output |
| [`--verbose`](#verbose) | `bool` | | Shorthand for `--format=pretty` |
| Name | Type | Default | Description |
|:------------------------|:-----------|:--------|:--------------------------------------------------------|
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--filter`](#filter) | `filter` | | Provide filter values |
| [`--format`](#format) | `string` | | Format the output |
| `--timeout` | `duration` | `20s` | Override the default timeout for loading builder status |
| [`--verbose`](#verbose) | `bool` | | Shorthand for `--format=pretty` |


<!---MARKER_GEN_END-->
Expand Down
11 changes: 6 additions & 5 deletions docs/reference/buildx_inspect.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,12 @@ Inspect current builder instance

### Options

| Name | Type | Default | Description |
|:----------------------------|:---------|:--------|:--------------------------------------------|
| [`--bootstrap`](#bootstrap) | `bool` | | Ensure builder has booted before inspecting |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| Name | Type | Default | Description |
|:----------------------------|:-----------|:--------|:--------------------------------------------------------|
| [`--bootstrap`](#bootstrap) | `bool` | | Ensure builder has booted before inspecting |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| `--timeout` | `duration` | `20s` | Override the default timeout for loading builder status |


<!---MARKER_GEN_END-->
Expand Down
11 changes: 6 additions & 5 deletions docs/reference/buildx_ls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,12 @@ List builder instances

### Options

| Name | Type | Default | Description |
|:----------------------|:---------|:--------|:----------------------|
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--format`](#format) | `string` | `table` | Format the output |
| `--no-trunc` | `bool` | | Don't truncate output |
| Name | Type | Default | Description |
|:----------------------|:-----------|:--------|:--------------------------------------------------------|
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--format`](#format) | `string` | `table` | Format the output |
| `--no-trunc` | `bool` | | Don't truncate output |
| `--timeout` | `duration` | `20s` | Override the default timeout for loading builder status |


<!---MARKER_GEN_END-->
Expand Down
23 changes: 12 additions & 11 deletions docs/reference/buildx_prune.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,18 @@ Remove build cache

### Options

| Name | Type | Default | Description |
|:--------------------------------------|:---------|:--------|:-------------------------------------------------------|
| [`-a`](#all), [`--all`](#all) | `bool` | | Include internal/frontend images |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--filter`](#filter) | `filter` | | Provide filter values |
| `-f`, `--force` | `bool` | | Do not prompt for confirmation |
| [`--max-used-space`](#max-used-space) | `bytes` | `0` | Maximum amount of disk space allowed to keep for cache |
| [`--min-free-space`](#min-free-space) | `bytes` | `0` | Target amount of free disk space after pruning |
| [`--reserved-space`](#reserved-space) | `bytes` | `0` | Amount of disk space always allowed to keep for cache |
| `--verbose` | `bool` | | Provide a more verbose output |
| Name | Type | Default | Description |
|:--------------------------------------|:-----------|:--------|:--------------------------------------------------------|
| [`-a`](#all), [`--all`](#all) | `bool` | | Include internal/frontend images |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`--filter`](#filter) | `filter` | | Provide filter values |
| `-f`, `--force` | `bool` | | Do not prompt for confirmation |
| [`--max-used-space`](#max-used-space) | `bytes` | `0` | Maximum amount of disk space allowed to keep for cache |
| [`--min-free-space`](#min-free-space) | `bytes` | `0` | Target amount of free disk space after pruning |
| [`--reserved-space`](#reserved-space) | `bytes` | `0` | Amount of disk space always allowed to keep for cache |
| `--timeout` | `duration` | `20s` | Override the default timeout for loading builder status |
| `--verbose` | `bool` | | Provide a more verbose output |


<!---MARKER_GEN_END-->
Expand Down
17 changes: 9 additions & 8 deletions docs/reference/buildx_rm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,15 @@ Remove one or more builder instances

### Options

| Name | Type | Default | Description |
|:------------------------------------|:---------|:--------|:-----------------------------------------|
| [`--all-inactive`](#all-inactive) | `bool` | | Remove all inactive builders |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`-f`](#force), [`--force`](#force) | `bool` | | Do not prompt for confirmation |
| [`--keep-daemon`](#keep-daemon) | `bool` | | Keep the BuildKit daemon running |
| [`--keep-state`](#keep-state) | `bool` | | Keep BuildKit state |
| Name | Type | Default | Description |
|:------------------------------------|:-----------|:--------|:--------------------------------------------------------|
| [`--all-inactive`](#all-inactive) | `bool` | | Remove all inactive builders |
| [`--builder`](#builder) | `string` | | Override the configured builder instance |
| `-D`, `--debug` | `bool` | | Enable debug logging |
| [`-f`](#force), [`--force`](#force) | `bool` | | Do not prompt for confirmation |
| [`--keep-daemon`](#keep-daemon) | `bool` | | Keep the BuildKit daemon running |
| [`--keep-state`](#keep-state) | `bool` | | Keep BuildKit state |
| `--timeout` | `duration` | `20s` | Override the default timeout for loading builder status |


<!---MARKER_GEN_END-->
Expand Down