From 77315839edfddbdac23d2b5058e1a98626c54625 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 7 Oct 2024 15:36:31 +0200 Subject: [PATCH] image-load: rewrite flag-description, move to docs Signed-off-by: Sebastiaan van Stijn --- cli/command/image/load.go | 7 +---- docs/reference/commandline/image_load.md | 39 +++++++++++++++++++++--- docs/reference/commandline/load.md | 10 +++--- 3 files changed, 40 insertions(+), 16 deletions(-) diff --git a/cli/command/image/load.go b/cli/command/image/load.go index 9a78318b4026..cd816208c05f 100644 --- a/cli/command/image/load.go +++ b/cli/command/image/load.go @@ -43,12 +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", "", - `Specify a platform from a multi-platform image to load. -If a platform is not specified, and the image is a multi-platform image, all platforms are loaded. - -Format: "os[/arch[/variant]]" -Example: "docker image load --platform linux/amd64"`) + flags.StringVar(&opts.platform, "platform", "", `Load only the given platform variant. Formatted as "os[/arch[/variant]]" (e.g. "linux/amd64")`) _ = flags.SetAnnotation("platform", "version", []string{"1.48"}) return cmd diff --git a/docs/reference/commandline/image_load.md b/docs/reference/commandline/image_load.md index 0d3e5c5adfc3..9ff107b9985e 100644 --- a/docs/reference/commandline/image_load.md +++ b/docs/reference/commandline/image_load.md @@ -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` | `string` | | Specify a platform from a multi-platform image to load.
If a platform is not specified, and the image is a multi-platform image, all platforms are loaded.

Format: `os[/arch[/variant]]`
Example: `docker image load --platform 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) | `string` | | Load only the given platform variant. Formatted as `os[/arch[/variant]]` (e.g. `linux/amd64`) | +| `-q`, `--quiet` | `bool` | | Suppress the load output | @@ -59,3 +59,32 @@ fedora 20 58394af37342 7 weeks ago fedora heisenbug 58394af37342 7 weeks ago 385.5 MB fedora latest 58394af37342 7 weeks ago 385.5 MB ``` + + +### Load a specific platform (--platform) + +The `--platform` option allows you to specify which platform-variant of the +image to load. By default, `docker load` loads all platform variants that +are present in the archive. Use the `--platform` option to specify which +platform variant of the image to load. An error is produced if the given +platform is not present in the archive. + +The platform option takes the `os[/arch[/variant]]` format, for example, +`linux/amd64` or `limux/arm64/v8`. Architecture and variant are optional, +and default to the daemon's native architecture if omitted. + +The following example loads the `linux/amd64` variant of an `alpine` image +from an archive that contains multiple platform variabts. + +```console +$ docker image load -i image.tar --platform=linux/amd64 +Loaded image: alpine:latest +``` + +The following example attempts to load a `linux/ppc64le` image from an +archive, but the given platform is not present in the archive; + +```console +$ docker image load -i image.tar --platform=linux/ppc64le +requested platform (linux/ppc64le) not found: image might be filtered out +``` diff --git a/docs/reference/commandline/load.md b/docs/reference/commandline/load.md index f366c58fb7f6..5afdcd42b5fa 100644 --- a/docs/reference/commandline/load.md +++ b/docs/reference/commandline/load.md @@ -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` | | Specify a platform from a multi-platform image to load.
If a platform is not specified, and the image is a multi-platform image, all platforms are loaded.

Format: `os[/arch[/variant]]`
Example: `docker image load --platform 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` | `string` | | Load only the given platform variant. Formatted as `os[/arch[/variant]]` (e.g. `linux/amd64`) | +| `-q`, `--quiet` | `bool` | | Suppress the load output |