[Request]: Consistent and useful multi-platform semantics for `pull`, `push`, `save`, `load`, `build`.

[jglogan]

Feature or enhancement request details

We've had #455 open to address #83 for quite a while now. Before we merge it (and celebrate that Alpine doesn't take a minute to pull) we wanted to make sure that we settle on the semantics for the multi-platform UX for all the image store operations.

This issue will be the umbrella for the whole of the work. We can close it once everything's merged / closed:

• Pull platform specific containers by default to save bandwidth (by 20x for some images) #83
• Consistent, useful multi-platform semantics for image push
• Consistent, useful multi-platform semantics for image save
• Consistent, useful multi-platform semantics for image load
• Consistent, useful multi-platform semantics for build
• [Bug]: Image save error output is too low-level. #874 (we can close and include in the image save issue once we've defined what we want)
• [Request]: Image save command: platform default to current #712 (we can close and include in the image save issue once we've defined what we want)
• [Request]: Choose platform with CONTAINER_DEFAULT_PLATFORM. #1252 (supports amd64-only development workflow)
• Complete a how-to.md section that summarizes how multi-platform works

Let's discuss alternatives here. We're taking "consistent" means something that's simple and easy to reason about while avoiding foolish consistency, and "useful" to mean something that avoids surprises and works well for the most common use cases.

We suppose that the most common use case is a development loop using native (arm64) containers.

However, we should be able to support an amd64-only development loop. You would use this if you're building and pushing your cloud deployment images on your local system (instead of using a CI system that builds/pushes amd64 or amd64+arm64), or if you really need to validate amd64 operation locally full time.

image pull and image push

Pull and push semantics are informed by #83:

• Without any options, the commands use the native platform (linux/arm64)
• The --platform option selects a single, specific platform
• The --all-platforms option selects all platforms

image save and image load

We have two options:

• Identical semantics as image pull and image push
• Default to saving and loading all platforms, instead of native

The former is definitely more consistent. Is the latter more useful?

• Time to read/write multi-platform archives is less of an issue.
• It may make more sense to write all platforms by default because if a user built a multi-platform image, they've indicated an intention that maybe we shouldn't undo on a save.

amd64 only development

For the amd64-only development loop, the proposal is to use an environment variable CONTAINER_DEFAULT_PLATFORM that functions similarly to DOCKER_DEFAULT_PLATFORM which if defined, overrides the native platform as the default for pull, push, build, create, and run.

--os and --arch

The -os and --arch shortcuts continue to function as they do today.

Multiple platform selection

The --platform only selects a single platform for all commands except build, but in the future we can consider allowing multiple platform selection for all commands.

Clear error reporting

We'll be replacing messages like these with errors that clearly indicate how platform options need to be modified to fix the issue

Error: notFound: "Content with digest sha256:6e7b17d6343f82de4aacb5687ded76f57aedf457e2906011093d98dfa4d11db4"

Containerization considerations

Containerization stores the complete remote image index regardless of pull qualifiers.

TODO - discuss how this works for:

• pull -> push
• pull platform A -> pull platform B

Code of Conduct

• I agree to follow this project's Code of Conduct