Support OCI 1.1 GA specifications

[yizha1]

Is your feature request related to a problem?

OCI v1.1 was released recently including:

• Distribution spec v1.1
• Image spec v1.1

The latest Notation release v1.1.0 uses image spec v1.1.0-rc.6 and by default use Referrers Tag schema when storing signatures. Besides uplifting dependency to the stable release v1.1 of the image spec, it is also recommended to revisit the experimental feature of "--allow-referrers-api flag" as registries will implement and enable Referrers API as OCI 1.1 is stable now. Some questions to answer:

• Should we just remove --allow-referrers-api flag from experimental feature, and make it a stable feature?
• Will Referrers Tag schema still be the default?
• What are the timelines of popular registries supporting OCI v1.1? Compatibility with most registries should be our goal.

What solution do you propose?

N/A

What alternatives have you considered?

N/A

Any additional context?

N/A

No response

[yizha1]

@priteshbandi @iamsamirzon We can discuss this issue for OCI 1.1 GA, and make a plan later.

[ChristianCiach]

Should we just remove --allow-referrers-api flag from experimental feature, and make it a stable feature?

Yes please :D

Will Referrers Tag schema still be the default?

Wouldn't this be a violation of the OCI spec? See https://github.com/opencontainers/distribution-spec/blob/main/spec.md

A client that pushes an image manifest with a defined subject field MUST verify the referrers API is available or fallback to updating the image index pushed to a tag described by the referrers tag schema. A client querying the referrers API and receiving a 404 Not Found MUST fallback to using an image index pushed to a tag described by the referrers tag schema.

Maybe I am reading this wrong, but it's my interpretation that the referrer-tag-schema is only valid as a fallback after a client tried to use the proper referrers-API first.

[yizha1]

Should we just remove --allow-referrers-api flag from experimental feature, and make it a stable feature?

Yes please :D

Will Referrers Tag schema still be the default?

Wouldn't this be a violation of the OCI spec? See https://github.com/opencontainers/distribution-spec/blob/main/spec.md

A client that pushes an image manifest with a defined subject field MUST verify the referrers API is available or fallback to updating the image index pushed to a tag described by the referrers tag schema. A client querying the referrers API and receiving a 404 Not Found MUST fallback to using an image index pushed to a tag described by the referrers tag schema.

Maybe I am reading this wrong, but it's my interpretation that the referrer-tag-schema is only valid as a fallback after a client tried to use the proper referrers-API first.

It is the current default behavior of using referrer-tag-schema. The fallback process depends on registries that implement the referrers API per the OCI 1.1 spec, so that clients have a deterministic way to perform a fallback. However, this is not the case before OCI 1.1 spec release, which is also one of the reasons that referrer-tag-schema is the default.

[sudo-bmitch]

It is the current default behavior of using referrer-tag-schema. The fallback process depends on registries that implement the referrers API per the OCI 1.1 spec, so that clients have a deterministic way to perform a fallback. However, this is not the case before OCI 1.1 spec release, which is also one of the reasons that referrer-tag-schema is the default.

That wasn't my understanding of the subject/referrer specs. I was under the impression that clients would push an artifact with a subject, and if the registry did not indicate they supported the referrers API, the client would fall back to pushing the tag. The detection method has changed from a 404 on the referrers API to a header on the manifest push, but it hasn't depended on the release date of the 1.1.0 distribution-spec. Registries will transition on their own schedule, and potentially not at all. Hopefully I'm just misinterpreting.

cc @sajayantony

[priteshbandi]

Should we just remove --allow-referrers-api flag from experimental feature, and make it a stable feature?

Yes, now that OCI 1.1 is generally available (GA), we should remove this feature from the experimental flag. However, before doing so, can we please ensure that allow-referrers-api complies with the GA specification?

Will Referrers Tag schema still be the default?

Yes, unless we bump up major version.

What are the timelines of popular registries supporting OCI v1.1? Compatibility with most registries should be our goal.

IMO it shouldn't matter. The feature will be accessible through the allow-referrers-api flag and should align with the OCI 1.1 specification. Thus, if a registry supports OCI 1.1, it should function properly. Additionally, we can always make minor adjustments later if needed.

[FeynmanZhou]

I second with @priteshbandi 's opinions above.

My two cents:

1. Make sure the behavior of using --allow-referrers-api has the automatic fallback mechanism to referrers tag schema for backward consideration consideration.
2. Not all users are aware of the OCI Spec v1.1 changes and they might be unfamiliar with referrers api/referrers tag schema. If there are two stable options (referrers api and referrers tag schema) for users in Notation v1.2.0, we should at least document the scenarios and benefits of using each option.

[yizha1]

Here is the summary per the discussion in the community meeting on Mar 4, 2024:

Current behavior

When experimental flag --allow-referrers-api is used, fallback to referrers Tag schema is enforced for all scenarios that referrers API does not work.

List of work items

• Update Notary Project signature specification to comply with OCI 1.1 specs
• Update --allow-referrers-api behavior to comply with OCI 1.1 distribution spec.
• Review and decide update existing flag --allow-referrers-api to a stable flag
• Review the default behavior of notation verify/ls/inspect as Referrers API supports returning preexisting image manifests that are listed in an image index tagged with the referrers tag schema. This will allow Notation to retrieve all the signatures no matter which method is used. Currently, if users do not specify --allow-referrers-api, only signatures using tag schema will be returned, and signatures stored with referrers API are missing.
• Create a document for users to understand default behaviors and options

/cc: @priteshbandi @FeynmanZhou @shizhMSFT @vaninrao10 to review above work items

[sudo-bmitch]

Watching the recording of yesterday's meeting has me concerned. Does the lack of the --allow-referrers-api flag change the behavior of the tool to push an image without a subject field, and maintain your own tag, separate from the OCI referrers fallback tag? If not, it looks like the flag is pushing a decision on the user that was designed by the spec to be done automatically.

From the spec, when pushing a manifest, if the subject field exists, the tool doing the pushing must push the fallback tag when the registry does not include the header to indicate registry supports the API:

When pushing a manifest with the subject field and the OCI-Subject header was not set, the client MUST: ...

https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#pushing-manifests-with-subject

When querying for referrers, the fallback is triggered on a 404 to the referrers API:

If the referrers API returns a 404, the client MUST fallback to pulling the referrers tag schema. The response SHOULD be an image index with the same content that would be expected from the referrers API. If the response to the referrers API is a 404, and the tag schema does not return a valid image index, the client SHOULD assume there are no referrers to the manifest.

https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers

The upgrade policy for registries requires that they include content previously pushed to the fallback tag, so there's no need to merge both:

When registries add support for the referrers API, this API needs to account for manifests that were pushed before the API was available using the Referrers Tag Schema. ...

https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#enabling-the-referrers-api

My concerns with making this a flag for the user (assuming that's switching whether the API or fallback tag is used) is that it creates a split brain issue where:

• content pushed using the API will not be discovered by clients querying using the fallback tag
• registries that support the API will still generate additional tags that clutter the tag namespace
• users may encounter errors depending on the registry if they attempt to use the API when it is not available