Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

spec: Multi-arch image management with ORAS #1514

Open
wants to merge 17 commits into
base: main
Choose a base branch
from
Prev Previous commit
Next Next commit
resolve comments
Signed-off-by: Feynman Zhou <feynmanzhou@microsoft.com>
FeynmanZhou committed Dec 9, 2024
commit f092b1438ff8a37910a50aedc58872b0216f95aa
36 changes: 11 additions & 25 deletions docs/proposals/multi-arch-image-mgmt.md
Original file line number Diff line number Diff line change
@@ -32,7 +32,7 @@ The `oras manifest` provides subcommands to push, fetch, and delete an image man

Specifically, there are limitations and problems to create and manage multi-arch images using `docker` or `docker buildx`:

### Lack of native support for local environment
#### Lack of native support for local environment

`docker buildx` confuses developers who are expecting to immediately run a multi-arch image after a successful build. Because `docker buildx` targets multiple architectures, it must be saved to a repository, not local storage. This requires the multi-arch image push to a repository and then a pull to run and test locally, which is inefficient for local development and testing.

@@ -64,7 +64,7 @@ The proposed CLI commands for managing a multi-arch image are listed below. The
- Create a multi-arch image: `oras manifest index create`
- Update a multi-arch image: `oras manifest index update`
- Inspect a multi-arch image: `oras manifest fetch`. Add two alias `oras manifest inspect` and `oras manifest show` for usability
FeynmanZhou marked this conversation as resolved.
Show resolved Hide resolved
- Add annotations to a multi-arch image: `oras manifest create --annotation`
- Add annotations to a multi-arch image: `oras manifest index create --annotation`

The proposal creates a multi-arch image using an OCI image index in an OCI image layout as a local storage, then push the multi-arch image to the registry with ORAS.

@@ -81,25 +81,23 @@ $ oras repo tags --oci-layout layout-dir

v1-linux-amd64
v1-linux-arm64
v1-linux-arm/v7
v1-linux-armv7
```

2. Create a multi-arch image by combining two image manifests into an image index, tag it with `v1` and push the tagged image index to an OCI image layout `layout-dir` automatically. Add annotations to this image index at the same time:

```bash
```console
$ oras manifest index create --oci-layout layout-dir:v1 v1-linux-amd64 v1-linux-arm64 --annotation "platform=multi-arch"
FeynmanZhou marked this conversation as resolved.
Show resolved Hide resolved
```

```bash
Fetching v1-linux-amd64
Fetched v1-linux-amd64
Fetching v1-linux-arm64
Fetched v1-linux-arm64
Packed edb5bc1f0b5c application/vnd.oci.image.index.v1+json
Pushed [oci-layout] layout-dir:v1
Digest: sha256:edb5bc1f0b5c21e9321b34e50c92beae739250fb8840905
Digest: sha256:edb5bc1f0b5c21e9321b34e50c92beae739250fb8840905

Status: An image index has been created and pushed to layout-dir:v1
Status: An image index has been created and pushed to layout-dir:v1
```

3. Inspect the image index from the OCI image layout:
@@ -141,15 +139,15 @@ $ oras manifest fetch --oci-layout layout-dir:v1 --pretty
4. Update the image index by adding a new architecture image in the OCI image layout:

```bash
$ oras manifest index update --oci-layout layout-dir:v1 --add linux-arm/v7
$ oras manifest index update --oci-layout layout-dir:v1 --add linux-armv7
```

```bash
Fetching v1
Fetched sha256:aba7563dbb28dcbe91b4d24ec84028af4ad97cfaf0cdf3fa550e8d619d5f36d1 v1
Fetching v1-linux-arm/v7
Fetched sha256:42c524c48e0672568dbd2842d3a0cb34a415347145ee9fe1c8abaf65e7455b46 v1-linux-arm/v7
Added sha256:42c524c48e0672568dbd2842d3a0cb34a415347145ee9fe1c8abaf65e7455b46 v1-linux-arm/v7
Fetching v1-linux-armv7
Fetched sha256:42c524c48e0672568dbd2842d3a0cb34a415347145ee9fe1c8abaf65e7455b46 v1-linux-armv7
Added sha256:42c524c48e0672568dbd2842d3a0cb34a415347145ee9fe1c8abaf65e7455b46 v1-linux-armv7
Updated sha256:7c65e066ada2a43efea2610451502498368ce3dcceef3e3d47d8fdcf32f47c57
Pushed [oci-layout] layout-dir:v1
Digest: sha256:7c65e066ada2a43efea2610451502498368ce3dcceef3e3d47d8fdcf32f47c57
@@ -241,16 +239,4 @@ In addition, `docker buildx` supports building a multi-arch image using the OCI
## Follow-up enhancements in the future releases

- Support showing platform information of tags in formatted output: https://github.com/oras-project/oras/issues/1547
- Support attach annotations to image index and its child image manifest in `oras attach`: https://github.com/oras-project/oras/issues/1531

## Appendix

### PoC

#### Create a multi-arch image as an OCI image index locally

Preview it on [![asciicast](https://asciinema.org/a/677877.svg)](https://asciinema.org/a/677877).

#### Update an existing OCI image index: add, remove, merge

Preview it on [![asciicast](https://asciinema.org/a/677890.svg)](https://asciinema.org/a/677890).
- Support attach annotations to image index and its child image manifest in `oras attach`: https://github.com/oras-project/oras/issues/1531