[Request]: Consistent and useful multi-platform semantics for `pull`, `push`, `save`, `load`, `build`.
- Dominant language
- Swift
- Stars
- 49.9k
- Forks
- 1.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 22
Description
### 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:
- [ ] #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`
- [ ] #874 (we can close and include in the `image save` issue once we've defined what we want)
- [ ] #712 (we can close and include in the `image save` issue once we've defined what we want)
- [x] #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
```console
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
- [x] I agree to follow this project's Code of Conduct
Contributor guide
Research direction
Start by reviewing the linked issues #83, #455, #874, #712, and #1252, then compare the proposed semantics for pull, push, save, load, and build. The work is complete when the checklist items are resolved, platform errors and defaults are settled, and the multi-platform behavior is summarized in a how-to.md section.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, linux, swift
- Domain
- cli, devops
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100