From 79207281fb4b602bf18ebcad04f0bb15b6c79237 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 6 May 2025 18:41:08 +0200 Subject: [PATCH 1/4] docs: import: fix anchor-links and minor touch-up - Put the content related to `--changes` under a heading with the correct anchor, so that it will be linked from the "options" table. - Move note about `sudo` to be under the right example. - Update some examples to directly read from a file instead of piping. - Add heading for the `--message` flag. Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/image_import.md | 70 +++++++++++++++------- 1 file changed, 49 insertions(+), 21 deletions(-) diff --git a/docs/reference/commandline/image_import.md b/docs/reference/commandline/image_import.md index 45591f7c34..01b80e3f93 100644 --- a/docs/reference/commandline/image_import.md +++ b/docs/reference/commandline/image_import.md @@ -9,11 +9,11 @@ Import the contents from a tarball to create a filesystem image ### Options -| Name | Type | Default | Description | -|:------------------|:---------|:--------|:--------------------------------------------------| -| `-c`, `--change` | `list` | | Apply Dockerfile instruction to the created image | -| `-m`, `--message` | `string` | | Set commit message for imported image | -| `--platform` | `string` | | Set platform if server is multi-platform capable | +| Name | Type | Default | Description | +|:------------------------------------------|:---------|:--------|:--------------------------------------------------| +| [`-c`](#change), [`--change`](#change) | `list` | | Apply Dockerfile instruction to the created image | +| [`-m`](#message), [`--message`](#message) | `string` | | Set commit message for imported image | +| `--platform` | `string` | | Set platform if server is multi-platform capable | @@ -28,10 +28,6 @@ specify an archive, Docker untars it in the container relative to the `/` the host. To import from a remote location, specify a `URI` that begins with the `http://` or `https://` protocol. -The `--change` option applies `Dockerfile` instructions to the image that is -created. Supported `Dockerfile` instructions: -`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` - ## Examples ### Import from a remote location @@ -50,12 +46,6 @@ Import to docker via pipe and `STDIN`. $ cat exampleimage.tgz | docker import - exampleimagelocal:new ``` -Import with a commit message. - -```console -$ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new -``` - Import to docker from a local archive. ```console @@ -68,17 +58,55 @@ $ docker import /path/to/exampleimage.tgz $ sudo tar -c . | docker import - exampleimagedir ``` -### Import from a local directory with new configurations - -```console -$ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir -``` - Note the `sudo` in this example – you must preserve the ownership of the files (especially root ownership) during the archiving with tar. If you are not root (or the sudo command) when you tar, then the ownerships might not get preserved. +### Import with new configurations (-c, --change) + +The `--change` option applies `Dockerfile` instructions to the image that is +created. Not all `Dockerfile` instructions are supported; the list of instructions +is limited to metadata (configuration) changes. The following `Dockerfile` +instructions are supported: + +- [`CMD`](https://docs.docker.com/reference/dockerfile/#cmd) +- [`ENTRYPOINT`](https://docs.docker.com/reference/dockerfile/#entrypoint) +- [`ENV`](https://docs.docker.com/reference/dockerfile/#env) +- [`EXPOSE`](https://docs.docker.com/reference/dockerfile/#expose) +- [`ONBUILD`](https://docs.docker.com/reference/dockerfile/#onbuild) +- [`USER`](https://docs.docker.com/reference/dockerfile/#user) +- [`VOLUME`](https://docs.docker.com/reference/dockerfile/#volume) +- [`WORKDIR`](https://docs.docker.com/reference/dockerfile/#workdir) + +The following example imports an image from a TAR-file containing a root-filesystem, +and sets the `DEBUG` environment-variable in the resulting image: + +```console +$ docker import --change "ENV DEBUG=true" ./rootfs.tgz exampleimagedir +``` + +### Import with a commit message (-m, --message) + +The `--message` (or `-m`) option allows you to set a custom comment in +the image's metadata. The following example imports an image from a local +archive and sets a custom message. + +```console +$ docker import --message "New image imported from tarball" ./rootfs.tgz exampleimagelocal:new +sha256:25e54c0df7dc49da9093d50541e0ed4508a6b78705057f1a9bebf1d564e2cb00 +``` + +After importing, the message is set in the "Comment" field of the image's +configuration, which is shown when viewing the image's history: + +```console +$ docker image history exampleimagelocal:new + +IMAGE CREATED CREATED BY SIZE COMMENT +25e54c0df7dc 2 minutes ago 53.6MB New image imported from tarball +``` + ### When the daemon supports multiple operating systems If the daemon supports multiple operating systems, and the image being imported From 2a67d601ad0b1332f20a4ada8092a994fbc72d04 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 6 May 2025 19:08:35 +0200 Subject: [PATCH 2/4] docs: import: update list of supported options for --change Update the list of accepted "change" commands to match what's accepted by the daemon. This list is the same for "docker commit" and "docker import", which is defined by the [`validCommitCommands`] variable. [`validCommitCommands`]: https://github.com/moby/moby/blob/v28.1.1/builder/dockerfile/builder.go#L30-L42 Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/image_import.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/reference/commandline/image_import.md b/docs/reference/commandline/image_import.md index 01b80e3f93..7fc9d5fa96 100644 --- a/docs/reference/commandline/image_import.md +++ b/docs/reference/commandline/image_import.md @@ -74,7 +74,10 @@ instructions are supported: - [`ENTRYPOINT`](https://docs.docker.com/reference/dockerfile/#entrypoint) - [`ENV`](https://docs.docker.com/reference/dockerfile/#env) - [`EXPOSE`](https://docs.docker.com/reference/dockerfile/#expose) +- [`HEALTHCHECK`](https://docs.docker.com/reference/dockerfile/#healthcheck) +- [`LABEL`](https://docs.docker.com/reference/dockerfile/#label) - [`ONBUILD`](https://docs.docker.com/reference/dockerfile/#onbuild) +- [`STOPSIGNAL`](https://docs.docker.com/reference/dockerfile/#stopsignal) - [`USER`](https://docs.docker.com/reference/dockerfile/#user) - [`VOLUME`](https://docs.docker.com/reference/dockerfile/#volume) - [`WORKDIR`](https://docs.docker.com/reference/dockerfile/#workdir) From 763ae3e0fb1f548c556df7f725c1f1fe18fa9a34 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 6 May 2025 19:24:46 +0200 Subject: [PATCH 3/4] docs: import: update documentation for --platform The `--platform` flag originally was added for the experimental LCOW feature and only accepted the target operating system. Current versions of Docker allow passing both OS and Architecture, so updating the documentation to reflect this. Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/image_import.md | 30 +++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/reference/commandline/image_import.md b/docs/reference/commandline/image_import.md index 7fc9d5fa96..c6a5db450e 100644 --- a/docs/reference/commandline/image_import.md +++ b/docs/reference/commandline/image_import.md @@ -13,7 +13,7 @@ Import the contents from a tarball to create a filesystem image |:------------------------------------------|:---------|:--------|:--------------------------------------------------| | [`-c`](#change), [`--change`](#change) | `list` | | Apply Dockerfile instruction to the created image | | [`-m`](#message), [`--message`](#message) | `string` | | Set commit message for imported image | -| `--platform` | `string` | | Set platform if server is multi-platform capable | +| [`--platform`](#platform) | `string` | | Set platform if server is multi-platform capable | @@ -120,3 +120,31 @@ daemon. ```console $ docker import --platform=linux .\linuximage.tar ``` + +### Set the platform for the imported image (--platform) + +The `--platform` option allows you to specify the platform for the imported +image. By default, the daemon's native platform is used as platform, but +the `--platform` option allows you to override the default, for example, in +situations where the imported root filesystem is for a different architecture +or operating system. + +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 imports an image from a root-filesystem in `rootfs.tgz`, +and sets the image's platform to `linux/amd64`; + +```console +$ docker image import --platform=linux/amd64 ./rootfs.tgz imported:latest +sha256:44a8b44157dad5edcff85f0c93a3e455f3b20a046d025af4ec50ed990d7ebc09 +``` + +After importing the image, the image's platform is set in the image's +configuration; + +```console +$ docker image inspect --format '{{.Os}}/{{.Architecture}}' imported:latest +linux/amd64 +``` From 4520a390d299bc35334b82f64f7ad6fa2c268b3a Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 6 May 2025 19:38:27 +0200 Subject: [PATCH 4/4] docs: import: add example for multiple --change flags Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/image_import.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/reference/commandline/image_import.md b/docs/reference/commandline/image_import.md index c6a5db450e..b08e85fb68 100644 --- a/docs/reference/commandline/image_import.md +++ b/docs/reference/commandline/image_import.md @@ -89,6 +89,19 @@ and sets the `DEBUG` environment-variable in the resulting image: $ docker import --change "ENV DEBUG=true" ./rootfs.tgz exampleimagedir ``` +The `--change` option can be set multiple times to apply multiple `Dockerfile` +instructions. The example below sets the `LABEL1` and `LABEL2` labels on +the imported image, in addition to the `DEBUG` environment variable from +the previous example: + +```console +$ docker import \ + --change "ENV DEBUG=true" \ + --change "LABEL LABEL1=hello" \ + --change "LABEL LABEL2=world" \ + ./rootfs.tgz exampleimagedir +``` + ### Import with a commit message (-m, --message) The `--message` (or `-m`) option allows you to set a custom comment in