commands: add timeout flag for create, inspect, ls and rm

crazy-max · crazy-max · commit b6c2272353ae · 2026-02-24T16:46:57.000+01:00
Signed-off-by: CrazyMax &lt;1951866+crazy-max@users.noreply.github.com&gt;
diff --git a/builder/builder.go b/builder/builder.go
@@ -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) {
@@ -526,7 +527,7 @@ func Create(ctx context.Context, txn *store.Txn, dockerCli command.Cli, opts Cre
 	}
 
 	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, _ := context.WithTimeoutCause(cancelCtx, 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())
diff --git a/commands/create.go b/commands/create.go
@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"time"
 
 	"github.com/docker/buildx/builder"
 	"github.com/docker/buildx/driver"
@@ -27,6 +28,7 @@ type createOptions struct {
 	buildkitdFlags      string
 	buildkitdConfigFile string
 	bootstrap           bool
+	timeout             time.Duration
 	// upgrade      bool // perform upgrade of the driver
 }
 
@@ -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
@@ -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")
+	setTimeoutFlag(flags, &options.timeout)
 
 	// hide builder persistent flag for this command
 	cobrautil.HideInheritedFlags(cmd, "builder")
diff --git a/commands/inspect.go b/commands/inspect.go
@@ -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 {
@@ -36,7 +37,7 @@ 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
+	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())
@@ -188,6 +189,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")
+	setTimeoutFlag(flags, &options.timeout)
 
 	return cmd
 }
diff --git a/commands/ls.go b/commands/ls.go
@@ -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 {
@@ -60,7 +61,7 @@ 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
+	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)
@@ -114,6 +115,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")
+	setTimeoutFlag(flags, &options.timeout)
 
 	// hide builder persistent flag for this command
 	cobrautil.HideInheritedFlags(cmd, "builder")
diff --git a/commands/rm.go b/commands/rm.go
@@ -21,6 +21,7 @@ type rmOptions struct {
 	keepDaemon  bool
 	allInactive bool
 	force       bool
+	timeout     time.Duration
 }
 
 const (
@@ -46,7 +47,11 @@ 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)
+	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) {
@@ -67,7 +72,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
 				}
@@ -120,6 +125,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")
+	setTimeoutFlag(flags, &options.timeout)
 
 	return cmd
 }
@@ -152,7 +158,7 @@ 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
+	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)
diff --git a/commands/root.go b/commands/root.go
@@ -3,6 +3,7 @@ package commands
 import (
 	"fmt"
 	"os"
+	"time"
 
 	historycmd "github.com/docker/buildx/commands/history"
 	imagetoolscmd "github.com/docker/buildx/commands/imagetools"
@@ -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 setTimeoutFlag(flags *pflag.FlagSet, target *time.Duration) {
+	flags.DurationVar(target, "timeout", 20*time.Second, "Override the default timeout for loading builder status")
+}
diff --git a/docs/reference/buildx_create.md b/docs/reference/buildx_create.md
@@ -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                                      |
 
 
diff --git a/docs/reference/buildx_inspect.md b/docs/reference/buildx_inspect.md
@@ -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-->
diff --git a/docs/reference/buildx_ls.md b/docs/reference/buildx_ls.md
@@ -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-->
diff --git a/docs/reference/buildx_rm.md b/docs/reference/buildx_rm.md
@@ -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-->

Original file line number	Diff line number	Diff line change
`@@ -346,6 +346,7 @@ type CreateOpts struct {`
`346`	`346`	`Use bool`
`347`	`347`	`Endpoint string`
`348`	`348`	`Append bool`
	`349`	`+ Timeout time.Duration`
`349`	`350`	`}`
`350`	`351`
`351`	`352`	`func Create(ctx context.Context, txn store.Txn, dockerCli command.Cli, opts CreateOpts) (Builder, error) {`
`@@ -526,7 +527,7 @@ func Create(ctx context.Context, txn *store.Txn, dockerCli command.Cli, opts Cre`
`526`	`527`	`}`
`527`	`528`
`528`	`529`	`cancelCtx, cancel := context.WithCancelCause(ctx)`
`529`		`- 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`
	`530`	`+ timeoutCtx, _ := context.WithTimeoutCause(cancelCtx, opts.Timeout, errors.WithStack(context.DeadlineExceeded)) //nolint:govet // no need to manually cancel this context as we already rely on parent`
`530`	`531`	`defer func() { cancel(errors.WithStack(context.Canceled)) }()`
`531`	`532`
`532`	`533`	`nodes, err := b.LoadNodes(timeoutCtx, WithData())`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,7 @@ import (`
`24`	`24`	`type inspectOptions struct {`
`25`	`25`	`bootstrap bool`
`26`	`26`	`builder string`
	`27`	`+ timeout time.Duration`
`27`	`28`	`}`
`28`	`29`
`29`	`30`	`func runInspect(ctx context.Context, dockerCli command.Cli, in inspectOptions) error {`
`@@ -36,7 +37,7 @@ func runInspect(ctx context.Context, dockerCli command.Cli, in inspectOptions) e`
`36`	`37`	`}`
`37`	`38`
`38`	`39`	`timeoutCtx, cancel := context.WithCancelCause(ctx)`
`39`		`- 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`
	`40`	`+ 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`
`40`	`41`	`defer func() { cancel(errors.WithStack(context.Canceled)) }()`
`41`	`42`
`42`	`43`	`nodes, err := b.LoadNodes(timeoutCtx, builder.WithData())`
`@@ -188,6 +189,7 @@ func inspectCmd(dockerCli command.Cli, rootOpts rootOptions) cobra.Command {`
`188`	`189`
`189`	`190`	`flags := cmd.Flags()`
`190`	`191`	`flags.BoolVar(&options.bootstrap, "bootstrap", false, "Ensure builder has booted before inspecting")`
	`192`	`+ setTimeoutFlag(flags, &options.timeout)`
`191`	`193`
`192`	`194`	`return cmd`
`193`	`195`	`}`