Skip to content

Add support for multiple platform options in image load and save #6126

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
merged 3 commits into from
Jul 24, 2025
Merged

Add support for multiple platform options in image load and save #6126

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
38b99ad
Add support for multiple platforms in docker image load.
ctalledo Jun 8, 2025
8993f54
Add support for multiple platforms in docker image save
ctalledo Jun 8, 2025
0ba4362
Update markdown docs to indicate multi-platform support in image load…
ctalledo Jun 10, 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
16 changes: 10 additions & 6 deletions cli/command/image/load.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,15 @@ import (
"github.com/docker/cli/internal/jsonstream"
"github.com/docker/docker/client"
"github.com/moby/sys/sequential"
ocispec "github.com/opencontainers/image-spec/specs-go/v1"
"github.com/pkg/errors"
"github.com/spf13/cobra"
)

type loadOptions struct {
input string
quiet bool
platform string
platform []string
}

// NewLoadCommand creates a new `docker load` command
Expand All @@ -42,7 +43,7 @@ func NewLoadCommand(dockerCli command.Cli) *cobra.Command {

flags.StringVarP(&opts.input, "input", "i", "", "Read from tar archive file, instead of STDIN")
flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress the load output")
flags.StringVar(&opts.platform, "platform", "", `Load only the given platform variant. Formatted as "os[/arch[/variant]]" (e.g., "linux/amd64")`)
flags.StringSliceVar(&opts.platform, "platform", []string{}, `Load only the given platform(s). Formatted as a comma-separated list of "os[/arch[/variant]]" (e.g., "linux/amd64,linux/arm64/v8").`)
_ = flags.SetAnnotation("platform", "version", []string{"1.48"})

_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
Expand Down Expand Up @@ -76,13 +77,16 @@ func runLoad(ctx context.Context, dockerCli command.Cli, opts loadOptions) error
options = append(options, client.ImageLoadWithQuiet(true))
}

if opts.platform != "" {
p, err := platforms.Parse(opts.platform)
platformList := []ocispec.Platform{}
for _, p := range opts.platform {
pp, err := platforms.Parse(p)
if err != nil {
return errors.Wrap(err, "invalid platform")
}
// TODO(thaJeztah): change flag-type to support multiple platforms.
options = append(options, client.ImageLoadWithPlatforms(p))
platformList = append(platformList, pp)
}
if len(platformList) > 0 {
options = append(options, client.ImageLoadWithPlatforms(platformList...))
}

response, err := dockerCli.Client().ImageLoad(ctx, input, options...)
Expand Down
18 changes: 17 additions & 1 deletion cli/command/image/load_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ func TestNewLoadCommandSuccess(t *testing.T) {
},
},
{
name: "with platform",
name: "with-single-platform",
args: []string{"--platform", "linux/amd64"},
imageLoadFunc: func(input io.Reader, options ...client.ImageLoadOption) (image.LoadResponse, error) {
// FIXME(thaJeztah): need to find appropriate way to test the result of "ImageHistoryWithPlatform" being applied
Expand All @@ -113,6 +113,22 @@ func TestNewLoadCommandSuccess(t *testing.T) {
return image.LoadResponse{Body: io.NopCloser(strings.NewReader("Success"))}, nil
},
},
{
name: "with-comma-separated-platforms",
args: []string{"--platform", "linux/amd64,linux/arm64/v8,linux/riscv64"},
imageLoadFunc: func(input io.Reader, options ...client.ImageLoadOption) (image.LoadResponse, error) {
assert.Check(t, len(options) > 0) // can be 1 or two depending on whether a terminal is attached :/
Copy link
Collaborator

@vvoland vvoland Jul 22, 2025

Choose a reason for hiding this comment

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

Hmm I'm not sure I understand this one. How does terminal affect parsing here?

Copy link
Contributor Author

@ctalledo ctalledo Jul 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I was simply copying a comment in the test right above this line (i.e., "with-single-platform"), but the underlying rationale for the comment comes from this code:

func runLoad(ctx context.Context, dockerCli command.Cli, opts loadOptions) error {
...
	var options []client.ImageLoadOption
	if opts.quiet || !dockerCli.Out().IsTerminal() {
		options = append(options, client.ImageLoadWithQuiet(true))
	}
...

Copy link
Collaborator

@vvoland vvoland Jul 23, 2025

Choose a reason for hiding this comment

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

Ah right.. We should apply these opts to a temporary var and then check the resulting opts struct, but we can't do that because these types are unexported..

I guess the only way to test it in this situation is by checking HTTP request at the HTTP client, but that would need rewriting the test a bit.

Although, I think the best solution would be to have a debug helper on the client side that would allow introspecting for testing purposes...

Copy link
Collaborator

@vvoland vvoland Jul 23, 2025

Choose a reason for hiding this comment

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

We should do that in a follow up though

return image.LoadResponse{Body: io.NopCloser(strings.NewReader("Success"))}, nil
},
},
{
name: "with-multiple-platform-options",
args: []string{"--platform", "linux/amd64", "--platform", "linux/arm64/v8", "--platform", "linux/riscv64"},
imageLoadFunc: func(input io.Reader, options ...client.ImageLoadOption) (image.LoadResponse, error) {
assert.Check(t, len(options) > 0) // can be 1 or two depending on whether a terminal is attached :/
return image.LoadResponse{Body: io.NopCloser(strings.NewReader("Success"))}, nil
},
},
}
for _, tc := range testCases {
t.Run(tc.name, func(t *testing.T) {
Expand Down
17 changes: 11 additions & 6 deletions cli/command/image/save.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,15 @@ import (
"github.com/docker/cli/cli/command/completion"
"github.com/docker/docker/client"
"github.com/moby/sys/atomicwriter"
ocispec "github.com/opencontainers/image-spec/specs-go/v1"
"github.com/pkg/errors"
"github.com/spf13/cobra"
)

type saveOptions struct {
images []string
output string
platform string
platform []string
}

// NewSaveCommand creates a new `docker save` command
Expand All @@ -41,7 +42,7 @@ func NewSaveCommand(dockerCli command.Cli) *cobra.Command {
flags := cmd.Flags()

flags.StringVarP(&opts.output, "output", "o", "", "Write to a file, instead of STDOUT")
flags.StringVar(&opts.platform, "platform", "", `Save only the given platform variant. Formatted as "os[/arch[/variant]]" (e.g., "linux/amd64")`)
flags.StringSliceVar(&opts.platform, "platform", []string{}, `Save only the given platform(s). Formatted as a comma-separated list of "os[/arch[/variant]]" (e.g., "linux/amd64,linux/arm64/v8")`)
_ = flags.SetAnnotation("platform", "version", []string{"1.48"})

_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
Expand All @@ -51,13 +52,17 @@ func NewSaveCommand(dockerCli command.Cli) *cobra.Command {
// runSave performs a save against the engine based on the specified options
func runSave(ctx context.Context, dockerCLI command.Cli, opts saveOptions) error {
var options []client.ImageSaveOption
if opts.platform != "" {
p, err := platforms.Parse(opts.platform)

platformList := []ocispec.Platform{}
for _, p := range opts.platform {
pp, err := platforms.Parse(p)
if err != nil {
return errors.Wrap(err, "invalid platform")
}
// TODO(thaJeztah): change flag-type to support multiple platforms.
options = append(options, client.ImageSaveWithPlatforms(p))
platformList = append(platformList, pp)
}
if len(platformList) > 0 {
options = append(options, client.ImageSaveWithPlatforms(platformList...))
}

var output io.Writer
Expand Down
20 changes: 20 additions & 0 deletions cli/command/image/save_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,26 @@ func TestNewSaveCommandSuccess(t *testing.T) {
return io.NopCloser(strings.NewReader("")), nil
},
},
{
args: []string{"--platform", "linux/amd64,linux/arm64/v8,linux/riscv64", "arg1"},
isTerminal: false,
imageSaveFunc: func(images []string, options ...client.ImageSaveOption) (io.ReadCloser, error) {
assert.Assert(t, is.Len(images, 1))
assert.Check(t, is.Equal("arg1", images[0]))
assert.Check(t, len(options) > 0) // can be 1 or 2 depending on whether a terminal is attached :/
return io.NopCloser(strings.NewReader("")), nil
},
},
{
args: []string{"--platform", "linux/amd64", "--platform", "linux/arm64/v8", "--platform", "linux/riscv64", "arg1"},
isTerminal: false,
imageSaveFunc: func(images []string, options ...client.ImageSaveOption) (io.ReadCloser, error) {
assert.Assert(t, is.Len(images, 1))
assert.Check(t, is.Equal("arg1", images[0]))
assert.Check(t, len(options) > 0) // can be 1 or 2 depending on whether a terminal is attached :/
return io.NopCloser(strings.NewReader("")), nil
},
},
}
for _, tc := range testCases {
t.Run(strings.Join(tc.args, " "), func(t *testing.T) {
Expand Down
0 ...load-command-success.with platform.golden → ...ess.with-comma-separated-platforms.golden
View file
Open in desktop
File renamed without changes.
1 change: 1 addition & 0 deletions cli/command/image/testdata/load-command-success.with-multiple-platform-options.golden
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Success
1 change: 1 addition & 0 deletions cli/command/image/testdata/load-command-success.with-single-platform.golden
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Success
10 changes: 5 additions & 5 deletions docs/reference/commandline/image_load.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ Load an image from a tar archive or STDIN

### Options

| Name | Type | Default | Description |
|:------------------------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------|
| [`-i`](#input), [`--input`](#input) | `string` | | Read from tar archive file, instead of STDIN |
| [`--platform`](#platform) | `string` | | Load only the given platform variant. Formatted as `os[/arch[/variant]]` (e.g., `linux/amd64`) |
| `-q`, `--quiet` | `bool` | | Suppress the load output |
| Name | Type | Default | Description |
|:------------------------------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------------------------------|
| [`-i`](#input), [`--input`](#input) | `string` | | Read from tar archive file, instead of STDIN |
| [`--platform`](#platform) | `stringSlice` | | Load only the given platform(s). Formatted as a comma-separated list of `os[/arch[/variant]]` (e.g., `linux/amd64,linux/arm64/v8`). |
| `-q`, `--quiet` | `bool` | | Suppress the load output |


<!---MARKER_GEN_END-->
Expand Down
8 changes: 4 additions & 4 deletions docs/reference/commandline/image_save.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ Save one or more images to a tar archive (streamed to STDOUT by default)

### Options

| Name | Type | Default | Description |
|:--------------------------|:---------|:--------|:-----------------------------------------------------------------------------------------------|
| `-o`, `--output` | `string` | | Write to a file, instead of STDOUT |
| [`--platform`](#platform) | `string` | | Save only the given platform variant. Formatted as `os[/arch[/variant]]` (e.g., `linux/amd64`) |
| Name | Type | Default | Description |
|:--------------------------|:--------------|:--------|:-----------------------------------------------------------------------------------------------------------------------------------|
| `-o`, `--output` | `string` | | Write to a file, instead of STDOUT |
| [`--platform`](#platform) | `stringSlice` | | Save only the given platform(s). Formatted as a comma-separated list of `os[/arch[/variant]]` (e.g., `linux/amd64,linux/arm64/v8`) |


<!---MARKER_GEN_END-->
Expand Down
10 changes: 5 additions & 5 deletions docs/reference/commandline/load.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ Load an image from a tar archive or STDIN

### Options

| Name | Type | Default | Description |
|:----------------|:---------|:--------|:-----------------------------------------------------------------------------------------------|
| `-i`, `--input` | `string` | | Read from tar archive file, instead of STDIN |
| `--platform` | `string` | | Load only the given platform variant. Formatted as `os[/arch[/variant]]` (e.g., `linux/amd64`) |
| `-q`, `--quiet` | `bool` | | Suppress the load output |
| Name | Type | Default | Description |
|:----------------|:--------------|:--------|:------------------------------------------------------------------------------------------------------------------------------------|
| `-i`, `--input` | `string` | | Read from tar archive file, instead of STDIN |
| `--platform` | `stringSlice` | | Load only the given platform(s). Formatted as a comma-separated list of `os[/arch[/variant]]` (e.g., `linux/amd64,linux/arm64/v8`). |
| `-q`, `--quiet` | `bool` | | Suppress the load output |


<!---MARKER_GEN_END-->
Expand Down
8 changes: 4 additions & 4 deletions docs/reference/commandline/save.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ Save one or more images to a tar archive (streamed to STDOUT by default)

### Options

| Name | Type | Default | Description |
|:-----------------|:---------|:--------|:-----------------------------------------------------------------------------------------------|
| `-o`, `--output` | `string` | | Write to a file, instead of STDOUT |
| `--platform` | `string` | | Save only the given platform variant. Formatted as `os[/arch[/variant]]` (e.g., `linux/amd64`) |
| Name | Type | Default | Description |
|:-----------------|:--------------|:--------|:-----------------------------------------------------------------------------------------------------------------------------------|
| `-o`, `--output` | `string` | | Write to a file, instead of STDOUT |
| `--platform` | `stringSlice` | | Save only the given platform(s). Formatted as a comma-separated list of `os[/arch[/variant]]` (e.g., `linux/amd64,linux/arm64/v8`) |


<!---MARKER_GEN_END-->
Expand Down
Loading