diff --git a/cli/command/image/save.go b/cli/command/image/save.go index c5a32859b8..dfceecc865 100644 --- a/cli/command/image/save.go +++ b/cli/command/image/save.go @@ -4,6 +4,7 @@ import ( "context" "io" + "github.com/containerd/platforms" "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/completion" @@ -13,8 +14,9 @@ import ( ) type saveOptions struct { - images []string - output string + images []string + output string + platform string } // NewSaveCommand creates a new `docker save` command @@ -38,7 +40,10 @@ 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.SetAnnotation("platform", "version", []string{"1.48"}) + _ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms) return cmd } @@ -52,7 +57,16 @@ func RunSave(ctx context.Context, dockerCli command.Cli, opts saveOptions) error return errors.Wrap(err, "failed to save image") } - responseBody, err := dockerCli.Client().ImageSave(ctx, opts.images, image.SaveOptions{}) + var options image.SaveOptions + if opts.platform != "" { + p, err := platforms.Parse(opts.platform) + if err != nil { + return errors.Wrap(err, "invalid platform") + } + options.Platform = &p + } + + responseBody, err := dockerCli.Client().ImageSave(ctx, opts.images, options) if err != nil { return err } diff --git a/cli/command/image/save_test.go b/cli/command/image/save_test.go index 8a399bdfa6..65d931566a 100644 --- a/cli/command/image/save_test.go +++ b/cli/command/image/save_test.go @@ -8,6 +8,7 @@ import ( "github.com/docker/cli/internal/test" "github.com/docker/docker/api/types/image" + ocispec "github.com/opencontainers/image-spec/specs-go/v1" "github.com/pkg/errors" "gotest.tools/v3/assert" is "gotest.tools/v3/assert/cmp" @@ -51,6 +52,11 @@ func TestNewSaveCommandErrors(t *testing.T) { args: []string{"-o", "/dev/null", "arg1"}, expectedError: "failed to save image: invalid output path: \"/dev/null\" must be a directory or a regular file", }, + { + name: "invalid platform", + args: []string{"--platform", "", "arg1"}, + expectedError: `invalid platform`, + }, } for _, tc := range testCases { tc := tc @@ -95,6 +101,16 @@ func TestNewSaveCommandSuccess(t *testing.T) { return io.NopCloser(strings.NewReader("")), nil }, }, + { + args: []string{"--platform", "linux/amd64", "arg1"}, + isTerminal: false, + imageSaveFunc: func(images []string, options image.SaveOptions) (io.ReadCloser, error) { + assert.Assert(t, is.Len(images, 1)) + assert.Check(t, is.Equal("arg1", images[0])) + assert.Check(t, is.DeepEqual(ocispec.Platform{OS: "linux", Architecture: "amd64"}, *options.Platform)) + return io.NopCloser(strings.NewReader("")), nil + }, + }, } for _, tc := range testCases { tc := tc diff --git a/docs/reference/commandline/image_save.md b/docs/reference/commandline/image_save.md index d6df5574c1..0a01c45b93 100644 --- a/docs/reference/commandline/image_save.md +++ b/docs/reference/commandline/image_save.md @@ -9,9 +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 | +| 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`) | @@ -59,3 +60,52 @@ You can even cherry-pick particular tags of an image repository. ```console $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy ``` + +### Save a specific platform (--platform) + +The `--platform` option allows you to specify which platform variant of the +image to save. By default, `docker save` saves all platform variants that +are present in the daemon's image store. Use the `--platform` option +to specify which platform variant of the image to save. An error is produced +if the given platform is not present in the local image store. + +The platform option takes the `os[/arch[/variant]]` format; for example, +`linux/amd64` or `linux/arm64/v8`. Architecture and variant are optional, +and default to the daemon's native architecture if omitted. + +The following example pulls the RISC-V variant of the `alpine:latest` image +and saves it to a tar archive. + +```console +$ docker pull --platform=linux/riscv64 alpine:latest +latest: Pulling from library/alpine +8c4a05189a5f: Download complete +Digest: sha256:beefdbd8a1da6d2915566fde36db9db0b524eb737fc57cd1367effd16dc0d06d +Status: Downloaded newer image for alpine:latest +docker.io/library/alpine:latest + +$ docker image save --platform=linux/riscv64 -o alpine-riscv.tar alpine:latest + +$ ls -lh image.tar +-rw------- 1 thajeztah staff 3.9M Oct 7 11:06 alpine-riscv.tar +``` + +The following example attempts to save a platform variant of `alpine:latest` +that doesn't exist in the local image store, resulting in an error. + +```console +$ docker image ls --tree +IMAGE ID DISK USAGE CONTENT SIZE IN USE +alpine:latest beefdbd8a1da 10.6MB 3.37MB +├─ linux/riscv64 80cde017a105 10.6MB 3.37MB +├─ linux/amd64 33735bd63cf8 0B 0B +├─ linux/arm/v6 50f635c8b04d 0B 0B +├─ linux/arm/v7 f2f82d424957 0B 0B +├─ linux/arm64/v8 9cee2b382fe2 0B 0B +├─ linux/386 b3e87f642f5c 0B 0B +├─ linux/ppc64le c7a6800e3dc5 0B 0B +└─ linux/s390x 2b5b26e09ca2 0B 0B + +$ docker image save --platform=linux/s390x -o alpine-s390x.tar alpine:latest +Error response from daemon: no suitable export target found for platform linux/s390x +``` diff --git a/docs/reference/commandline/save.md b/docs/reference/commandline/save.md index 1c9f9c53db..19e8c353da 100644 --- a/docs/reference/commandline/save.md +++ b/docs/reference/commandline/save.md @@ -9,9 +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 | +| 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`) |