Update --load with a note highlight

[larsqa]

Proposal after discussion of #1220

Single platform for the --load option should be more highlighted, with the help of a Note?

[larsqa]

I don't understand that the first part of this comment is trying to say. And push is documented separately. If there is a note, it should just say that docker load command currently does not support loading multi-platform images so only a single platform can be specified for such builds.

That's fair.

The part in question:

--load is the default option during a docker buildx build command. These builds store images locally. At the moment, multi-platform builds are only possible using remote registries.

From my point of view and understanding, I assume that

• --load is the default option for the buildx command. I wasn't able to figure out any other logic default option for this setting.
• --load is the common-expected behaviour known in Docker by storing images locally.

I felt that mentioning that, before explaining the --push alternative which has multi-arch support, would be helpful for less-knowledgable devs like me.

[tonistiigi]

--load is not default(why would you set it then). You might be thinking about Docker driver without --output.

Looking at https://github.com/docker/buildx/blob/e12827910c278b76b9bb1050e7157354db3b1f42/docs/reference/buildx_build.md#docker the multi-platform case is already described there. And it is linked from --load. We can update the wording there to make it more clear that a single platform works.

[larsqa]

--load is not default(why would you set it then). You might be thinking about Docker driver without --output.

Ohhh alright!

Looking at https://github.com/docker/buildx/blob/e12827910c278b76b9bb1050e7157354db3b1f42/docs/reference/buildx_build.md#docker the multi-platform case is already described there. And it is linked from --load. We can update the wording there to make it more clear that a single platform works.

---

I looked at your linked resource, which mentions:

Currently, multi-platform images cannot be exported with the docker export type. The most common usecase for multi-platform images is to directly push to a registry (see registry).

The "registry" this part links to mentions:

The registry exporter is a shortcut for type=image,push=true.

Looking a bit further, the Push the build result to a registry (--push) mentions:

Shorthand for --output=type=registry. Will automatically push the build result to registry.

As a reader, I get a feeling that there are now 3 ways to push to the registry in order to use multi-platform:

• -- type=image,push=true
• --output=type=registry
• --push (shorthand of above)

While I believe they all use the underlying process, it still confuses me as a reader.

---

Here are my propositions, then:

• As you mention, mention that docker load does currently not support loading multi-platform images so only a single platform can be specified for such builds.
• Add to docker load that pushing to a registry with --push allows for mulit-platform support.
• Improve the push/registry to allow for one option to push to a registry and shorten it with push?

[thaJeztah]

--load is not default(why would you set it then). You might be thinking about Docker driver without --output. Ohhh alright!

Some related discussion on that in https://github.com/docker/cli/pull/3676#issuecomment-1157622147

[tonistiigi]

Here are my propositions, then:

I don't really understand these.

As you mention, mention that docker load does currently not support loading multi-platform images so only a single platform can be specified for such builds.

This is already documented. If you think you can improve its readability, go ahead, and we will check.

Add to docker load that pushing to a registry with --push allows for mulit-platform support.

Load should not document push options. Push should document push options.

Improve the push/registry to allow for one option to push to a registry and shorten it with push?

Don't understand what you mean here.

[jedevc]

Closing this due to inactivity - @larsqa, if you want to re-open, please go ahead! :tada: