apple / apple/container

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

Open
#913 0 comments 1 reaction 0 assignees View on GitHub
enhancement next
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.