From ed3c412e147b43c49ad3fc622bc835db3e64b2ad Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Mon, 21 Aug 2023 09:53:44 +0800 Subject: [PATCH 1/5] update compatibility mode doc to align with ORAS v1.1.0 Signed-off-by: Feynman Zhou --- docs/proposals/compatibility-mode.md | 47 +++++++++------------------- 1 file changed, 15 insertions(+), 32 deletions(-) diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md index 90c5d61fd..154a324fc 100644 --- a/docs/proposals/compatibility-mode.md +++ b/docs/proposals/compatibility-mode.md @@ -1,60 +1,43 @@ # Compatibility mode for ORAS -This document is for adding a document to elaborate the compatibility mode for ORAS CLI which was proposed in [issue #720](https://github.com/oras-project/oras/issues/720). +OCI group announced the [Image-spec v1.1.0-rc4](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md) and [Distribution-spec ](https://github.com/opencontainers/distribution-spec) in Sep 2022. A notable breaking change is that the OCI Artifact Manifest no longer exists in the OCI Image-spec v1.1.0-rc4. -## Background +Two new experimental flag `--image-spec` and `--distribution-spec` were introduced to ORAS CLI v1.0.0 as explained in [this doc](https://github.com/oras-project/oras/blob/release-1.0/docs/proposals/compatibility-mode.md). To align with the OCI Image-spec v1.1.0-rc4, we need to adjust the flag `--image-spec` in ORAS v1.1.0 accordingly. -OCI group announced the release of v1.1 for [Image-spec](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc1/artifact.md) and [Distribution-spec](https://github.com/opencontainers/distribution-spec) in Sep 2022. It supports the OCI artifact manifest and provides a new referrers discovery API that allows artifact references. - -Since 0.16.0, ORAS supports pushing OCI artifact manifest to OCI v1.0 compliant registries. However, the new manifest type may not be supported on the consumer side (e.g. self-crafted scripts) or in those OCI v1.0 compliant registries. To enable ORAS to work with popular registries, it provides backward compatibility which supports two types of manifest and allows fallback to upload the OCI image manifest to OCI v1.0 compliant registries or those which enabled OCI image manifest storage. - -## Challenge - -The fallback attempted by ORAS may fail since there is no deterministic way to confirm if a registry supporting OCI artifact manifest due to no consistent error response. - -You can find the testing result of the implementation result for OCI Spec from this [blog](https://toddysm.com/2023/01/05/oci-artifct-manifests-oci-referrers-api-and-their-support-across-registries-part-1/). On the other hand, users may want to force-push a specific manifest type to a registry for some reason. - -The current workaround for enabling a kind of compatibility mode is to specify a `--config` flag when using `oras push`. Since the OCI artifact manifest does not have a `config`, it will push an OCI image manifest instead. It is not user-friendly and is a bit hacky. It would be better if we can provide a compatibility mode to easily customize and switch the manifest uploading behavior, and enable users to handle the incompatibility problem when using ORAS across different registries. +This document elaborates on the changes of ORAS CLI v1.1.0 proposed in [issue #1043](https://github.com/oras-project/oras/issues/1043). ## Goals -- Provide different options to allow users to customize the manifest uploading behavior to the registry +- Provide different options to allow users to customize the manifest build and distribution behavior - Provide an easy-to-use and secure user experience when switching the behaviors -- Enable ORAS to work with more registries flexibly +- Enable ORAS to work with more OCI registries flexibly ## Solution -Adding new flags to `oras push` and `oras attach` respectively with different variables to configure the manifest uploading behaviors. - -- Adding a flag `--image-spec` to `oras push` and `oras attach` to force uploading a specific manifest type to registry -- Adding a flag `--distribution-spec` to `oras attach`, `oras attach`, `oras cp`, and `oras manifest push` to configure compatibility with registry when pushing or copying an image/artifact manifest. This flag is also applicable to `oras discover` for filtering the referrers. - -### Force uploading a specific manifest type using a flag `--image-spec` +Using flags in `oras push` and `oras attach` respectively with different variables to configure the manifest build and distribution behaviors. -It follows `--image-spec -` to enable configuration of using which spec version and manifest type. Currently, it only supports specifying v1.1 as the spec version. +- Using a flag `--image-spec` with `oras push` +- Using a flag `--distribution-spec` with `oras attach`, `oras attach`, `oras cp`, and `oras manifest push` to configure compatibility with registry when pushing or copying an image/artifact manifest. This flag is also applicable to `oras discover` for filtering the referrers. -| registry support | v1.1-artifact | v1.1-image | -| :-------------------------------------- | ----------------- | -------------- | -| OCI spec 1.0 | no | yes[^footnote] | -| OCI spec 1.1 without referrers API | yes | yes | -| OCI spec 1.1 with referrers API support | yes | yes | +### Build and push OCI image manifest type using a flag `--image-spec` -> [^footnote]: It may fail when the OCI spec 1.0 compliant registry doesn't accept the `subject` field included in the image manifest. +It follows `--image-spec ` to enable configuration of using which spec version. Currently, it supports specifying `v1.0` and `v1.1` as the spec version. -If users want to force pushing a specific version of OCI artifact manifest to a registry, they can use `--image-spec v1.1-artifact`. An OCI artifact manifest will be packed and uploaded. Users might choose it for security requirements, such as pushing a signature to a registry without changing its digest. For example: +If users want to build an OCI Image Manifest and push it to a OCI Spec-v1.1.0 compliant registry or OCI image layout, they can use `--image-spec v1.1`. An OCI Image Manifest that conforms the OCI Image-spec v1.1.0 will be packed and uploaded. For example: ```bash oras push localhost:5000/hello-artifact:v1 \ - --image-spec v1.1-artifact \ + --image-spec v1.1 \ + --config config.json:application/example.config+json --artifact-type sbom/example \ sbom.json ``` -If users want to force pushing an OCI image manifest, no matter whether the registry is compliant with the OCI Spec v1.0 or v1.1, using `--image-spec v1.1-image` will only upload the OCI image manifest to a registry. This option is useful when users have concerns to use OCI artifact manifest or need to migrate content to OCI v1.0 compliant registry. For example: +If users want to build an OCI Image Manifest and push it to a OCI Spec-v1.0.0 compliant registry or OCI image layout, they can use `--image-spec v1.0`. An OCI Image Manifest that conforms the OCI Image-spec v1.0.0 will be packed and uploaded. For example: ```bash oras push localhost:5000/hello-artifact:v1 \ - --image-spec v1.1-image \ + --image-spec v1.0 \ --artifact-type sbom/example \ sbom.json ``` From 57c7ec67b33bd3af9fc13cbaf6c034322f5bef49 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 1 Sep 2023 17:54:59 +0800 Subject: [PATCH 2/5] update compatibility mode doc Signed-off-by: Feynman Zhou --- docs/proposals/compatibility-mode.md | 40 +++++++++++----------------- 1 file changed, 15 insertions(+), 25 deletions(-) diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md index 154a324fc..864a09871 100644 --- a/docs/proposals/compatibility-mode.md +++ b/docs/proposals/compatibility-mode.md @@ -9,36 +9,26 @@ This document elaborates on the changes of ORAS CLI v1.1.0 proposed in [issue #1 ## Goals - Provide different options to allow users to customize the manifest build and distribution behavior -- Provide an easy-to-use and secure user experience when switching the behaviors -- Enable ORAS to work with more OCI registries flexibly +- Provide an easy-to-use and secure user experience when push content to OCI registries +- Enable ORAS to work with more OCI registries ## Solution -Using flags in `oras push` and `oras attach` respectively with different variables to configure the manifest build and distribution behaviors. +Using the following flags in `oras push` and `oras attach` respectively with different variables to configure the manifest build and distribution behaviors. - Using a flag `--image-spec` with `oras push` -- Using a flag `--distribution-spec` with `oras attach`, `oras attach`, `oras cp`, and `oras manifest push` to configure compatibility with registry when pushing or copying an image/artifact manifest. This flag is also applicable to `oras discover` for filtering the referrers. +- Using a flag `--distribution-spec` with `oras attach`, `oras attach`, `oras cp`, and `oras manifest push` to configure compatibility with registry when pushing or copying an OCI image manifest. This flag is also applicable to `oras discover` for filtering the referrers. -### Build and push OCI image manifest type using a flag `--image-spec` +### Build and push OCI image manifest using a flag `--image-spec` -It follows `--image-spec ` to enable configuration of using which spec version. Currently, it supports specifying `v1.0` and `v1.1` as the spec version. +Use the flag `--image-spec ` in `oras push` to specify which version of the OCI Image-spec when building and pushing an OCI image manifest. It supports specifying the option `v1.0` or `v1.1` as the spec version. The option `v1.1` is the default behavior in `oras push` since ORAS CLI v1.1.0 so users don't need to manually specify this option. -If users want to build an OCI Image Manifest and push it to a OCI Spec-v1.1.0 compliant registry or OCI image layout, they can use `--image-spec v1.1`. An OCI Image Manifest that conforms the OCI Image-spec v1.1.0 will be packed and uploaded. For example: +If users want to build an OCI image manifest to a registry that compliant with OCI Spec v1.0, they can specify `--image-spec v1.0`. An OCI image manifest that conforms the OCI Image-spec v1.0.0 will be packed and uploaded. For example: ```bash -oras push localhost:5000/hello-artifact:v1 \ - --image-spec v1.1 \ - --config config.json:application/example.config+json - --artifact-type sbom/example \ - sbom.json -``` - -If users want to build an OCI Image Manifest and push it to a OCI Spec-v1.0.0 compliant registry or OCI image layout, they can use `--image-spec v1.0`. An OCI Image Manifest that conforms the OCI Image-spec v1.0.0 will be packed and uploaded. For example: - -```bash -oras push localhost:5000/hello-artifact:v1 \ +oras push localhost:5000/hello-world:v1 \ --image-spec v1.0 \ - --artifact-type sbom/example \ + --artifact-type application/vnd.me.config \ sbom.json ``` @@ -52,24 +42,24 @@ Based on the Referrers API status in the registry, users can use flag `--distrib | OCI spec 1.1 without referrers API | no | yes | | OCI spec 1.1 with referrers API support | yes | yes | -Using a flag `--distribution-spec v1.1-referrers-api` to disable backward compatibility. It only allows uploading OCI artifact manifest to OCI v1.1 compliant registry with Referrers API enabled. This is the most strict option for setting compatibility with the registry. Users might choose it for security requirements. +Using a flag `--distribution-spec v1.1-referrers-api` to disable backward compatibility. It only allows uploading OCI image manifest to OCI v1.1 compliant registry with Referrers API enabled. This is the most strict option for setting compatibility with the registry. Users might choose it for security requirements. -For example, using this flag, ORAS will attach OCI artifact manifest only to an OCI v1.1 compliant registry with Referrers API enabled and no further actions for maintaining artifact references in registries. +For example, using this flag, ORAS will attach OCI image manifest only to an OCI v1.1 compliant registry with Referrers API enabled and no further actions for maintaining references in OCI registries. ```bash -oras attach localhost:5000/hello-artifact:v1 \ +oras attach localhost:5000/hello-world:v1 \ --artifact-type sbom/example \ --distribution-spec v1.1-referrers-api \ sbom.json ``` -Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compatibility with the registry. It will first attempt to upload the OCI artifact manifest with the [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema) regardless of whether the registry complies with the OCI Spec v1.0 or v1.1 or supports Referrers API. For example: +Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compatibility with the registry. It will first attempt to upload the OCI image manifest with the [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema) regardless of whether the registry complies with the OCI Spec v1.0 or v1.1 or supports Referrers API. For example: ```bash -oras attach localhost:5000/hello-artifact:v1 \ +oras attach localhost:5000/hello-world:v1 \ --artifact-type sbom/example \ --distribution-spec v1.1-referrers-tag \ sbom.json ``` -Similarly, users can use `oras cp`, and `oras manifest push` with the flag `--distribution-spec` to configure compatibility with registry when pushing or copying an image/artifact manifest, or use `oras discover` with the flag `--distribution-spec` for filtering the referrers in the view. \ No newline at end of file +Similarly, users can use `oras cp`, and `oras manifest push` with the flag `--distribution-spec` to configure compatibility with registry when pushing or copying an OCI image manifest, or use `oras discover` with the flag `--distribution-spec` for filtering the referrers in the view. \ No newline at end of file From 23dbb1c803ce33b512bc553855c975e9f6fd7ef2 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 1 Sep 2023 18:03:38 +0800 Subject: [PATCH 3/5] update compatibility mode doc Signed-off-by: Feynman Zhou --- docs/proposals/compatibility-mode.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md index 864a09871..739c641c8 100644 --- a/docs/proposals/compatibility-mode.md +++ b/docs/proposals/compatibility-mode.md @@ -1,10 +1,10 @@ # Compatibility mode for ORAS -OCI group announced the [Image-spec v1.1.0-rc4](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md) and [Distribution-spec ](https://github.com/opencontainers/distribution-spec) in Sep 2022. A notable breaking change is that the OCI Artifact Manifest no longer exists in the OCI Image-spec v1.1.0-rc4. +OCI group announced the [Image-spec v1.1.0-rc4](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md) and [Distribution-spec v1.1.0-rc3](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0-rc3) in July 2023. A notable breaking change is that the OCI Artifact Manifest no longer exists in the OCI Image-spec v1.1.0-rc4. -Two new experimental flag `--image-spec` and `--distribution-spec` were introduced to ORAS CLI v1.0.0 as explained in [this doc](https://github.com/oras-project/oras/blob/release-1.0/docs/proposals/compatibility-mode.md). To align with the OCI Image-spec v1.1.0-rc4, we need to adjust the flag `--image-spec` in ORAS v1.1.0 accordingly. +Two new experimental flag `--image-spec` and `--distribution-spec` were introduced to ORAS CLI v1.0.0 as explained in [this doc](https://github.com/oras-project/oras/blob/release-1.0/docs/proposals/compatibility-mode.md). To align with the OCI Image-spec v1.1.0-rc4, the flag `--image-spec` and its options are changed in ORAS v1.1.0 accordingly. -This document elaborates on the changes of ORAS CLI v1.1.0 proposed in [issue #1043](https://github.com/oras-project/oras/issues/1043). +This document elaborates on the major changes of ORAS CLI v1.1.0 proposed in [issue #1043](https://github.com/oras-project/oras/issues/1043). ## Goals From 630b5efb58f2eeee4eeaaf2b49e1ac997169fc2c Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 1 Sep 2023 18:05:52 +0800 Subject: [PATCH 4/5] refine doc Signed-off-by: Feynman Zhou --- docs/proposals/compatibility-mode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md index 739c641c8..88d170cd1 100644 --- a/docs/proposals/compatibility-mode.md +++ b/docs/proposals/compatibility-mode.md @@ -2,7 +2,7 @@ OCI group announced the [Image-spec v1.1.0-rc4](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md) and [Distribution-spec v1.1.0-rc3](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0-rc3) in July 2023. A notable breaking change is that the OCI Artifact Manifest no longer exists in the OCI Image-spec v1.1.0-rc4. -Two new experimental flag `--image-spec` and `--distribution-spec` were introduced to ORAS CLI v1.0.0 as explained in [this doc](https://github.com/oras-project/oras/blob/release-1.0/docs/proposals/compatibility-mode.md). To align with the OCI Image-spec v1.1.0-rc4, the flag `--image-spec` and its options are changed in ORAS v1.1.0 accordingly. +Two new experimental flag `--image-spec` and `--distribution-spec` were introduced to commands `oras push` and `oras attach` in ORAS CLI v1.0.0 as explained in [this doc](https://github.com/oras-project/oras/blob/release-1.0/docs/proposals/compatibility-mode.md). To align with the OCI Image-spec v1.1.0-rc4, the flag `--image-spec` and its options are changed in ORAS v1.1.0 accordingly. This document elaborates on the major changes of ORAS CLI v1.1.0 proposed in [issue #1043](https://github.com/oras-project/oras/issues/1043). From 099784acc1cadeadc08b9081c11babc925eae5db Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Fri, 1 Sep 2023 20:09:48 +0800 Subject: [PATCH 5/5] refine doc Signed-off-by: Feynman Zhou --- docs/proposals/compatibility-mode.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/proposals/compatibility-mode.md b/docs/proposals/compatibility-mode.md index 88d170cd1..c9125bf30 100644 --- a/docs/proposals/compatibility-mode.md +++ b/docs/proposals/compatibility-mode.md @@ -2,7 +2,7 @@ OCI group announced the [Image-spec v1.1.0-rc4](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md) and [Distribution-spec v1.1.0-rc3](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0-rc3) in July 2023. A notable breaking change is that the OCI Artifact Manifest no longer exists in the OCI Image-spec v1.1.0-rc4. -Two new experimental flag `--image-spec` and `--distribution-spec` were introduced to commands `oras push` and `oras attach` in ORAS CLI v1.0.0 as explained in [this doc](https://github.com/oras-project/oras/blob/release-1.0/docs/proposals/compatibility-mode.md). To align with the OCI Image-spec v1.1.0-rc4, the flag `--image-spec` and its options are changed in ORAS v1.1.0 accordingly. +Two experimental flags `--image-spec` and `--distribution-spec` were introduced to commands `oras push` and `oras attach` in ORAS CLI v1.0.0 as explained in [this doc](https://github.com/oras-project/oras/blob/v1.0.1/docs/proposals/compatibility-mode.md). To align with the OCI Image-spec v1.1.0-rc4, the flag `--image-spec` and its options are changed in ORAS v1.1.0 accordingly. This document elaborates on the major changes of ORAS CLI v1.1.0 proposed in [issue #1043](https://github.com/oras-project/oras/issues/1043). @@ -17,13 +17,13 @@ This document elaborates on the major changes of ORAS CLI v1.1.0 proposed in [is Using the following flags in `oras push` and `oras attach` respectively with different variables to configure the manifest build and distribution behaviors. - Using a flag `--image-spec` with `oras push` -- Using a flag `--distribution-spec` with `oras attach`, `oras attach`, `oras cp`, and `oras manifest push` to configure compatibility with registry when pushing or copying an OCI image manifest. This flag is also applicable to `oras discover` for filtering the referrers. +- Using a flag `--distribution-spec` with `oras attach`, `oras cp`, and `oras manifest push` to configure compatibility with registry when pushing or copying an OCI image manifest. This flag is also applicable to `oras discover` for viewing and filtering the referrers. ### Build and push OCI image manifest using a flag `--image-spec` Use the flag `--image-spec ` in `oras push` to specify which version of the OCI Image-spec when building and pushing an OCI image manifest. It supports specifying the option `v1.0` or `v1.1` as the spec version. The option `v1.1` is the default behavior in `oras push` since ORAS CLI v1.1.0 so users don't need to manually specify this option. -If users want to build an OCI image manifest to a registry that compliant with OCI Spec v1.0, they can specify `--image-spec v1.0`. An OCI image manifest that conforms the OCI Image-spec v1.0.0 will be packed and uploaded. For example: +If users want to build an OCI image manifest to a registry that compliant with OCI Spec v1.0, they can specify `--image-spec v1.0`. An OCI image manifest that conforms the OCI Image-spec v1.0.2 will be packed and uploaded. For example ```bash oras push localhost:5000/hello-world:v1 \ @@ -53,7 +53,7 @@ oras attach localhost:5000/hello-world:v1 \ sbom.json ``` -Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compatibility with the registry. It will first attempt to upload the OCI image manifest with the [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema) regardless of whether the registry complies with the OCI Spec v1.0 or v1.1 or supports Referrers API. For example: +Using `--distribution-spec v1.1-referrers-tag` to enable maximum backward compatibility with the registry. It will first attempt to upload the OCI image manifest with the [referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#referrers-tag-schema) regardless of whether the registry complies with the OCI Spec v1.0 or v1.1 or supports Referrers API. For example: ```bash oras attach localhost:5000/hello-world:v1 \