opencontainers / wg-reference-types Goto Github PK

Hiya! Per @jdolitsky email I went over the "Cherry Pick" 🍒 proposal and here are some quick questions:

Added annotations

So for annotations I noticed we are adding new ones:

https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_E.md#annotations

But we aren't adding a simple one for something like "name." For a client that intends to store and retrieve, I think right now our main (only?) option is to save a custom annotation, but then it means it could be different based on the client. Would it hurt to allow adding a more official "name" annotation org.opencontainers.artifact.name to store an original basename, or a name relative to the upload root (no direct paths)? It would be akin to org.opencontainers.image.title but title is weird for an artifact, so maybe just name.

Architectures

We are adding org.opencontainers.platform.architecture - is this a scoped set? Is architecture == microarchitecture? E.g., if this is the granularity I have:

https://github.com/archspec/archspec-json/blob/51f75b644a7efd6b2c4dc1a07542856ee2ba6229/cpu/microarchitectures.json

Is that going to be supported?

Referrers

"referrers" is really hard to say, and somehow reminds me of the word "furry" because of the two r's (no idea why, lol). Why can't it just be "refers" ? Also, is it one directional?

Pagination

Is it implied there is a ?page parameter included in Link? https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_E.md#ordering-and-pagination so someone doesn't always have to start at 0? Might be good to mention.

Tags when referrers not supported

Is this done so you can push something to a registry (that doesn't support referrers) that you might want to eventually push to one that does support it? If objects are now like a graph, how are these basic operations done without losing important nodes?

And I didn't read through all the requirements - but those should be some questions to get us started!

Following up with adding filtering for artifactType, now that we have it as a standalone field (#59).

I've opened #74 and would like to propose a vote for the community to voice their opinion on this proposal. Vote by giving a 👍 to either of the comments below.

Using "reference" in this working group and the resulting proposals will be confusing with the existing term for a "reference" which is a name used to pull images from a registry (see distribution/distribution). We should avoid using that name where possible. Is "referrers" and "refer" better?

Please adhere to the format of the template.

Primary contact: @dlorenc

Please adhere to the format of the template.

Primary contact: @SteveLasker

With great power comes great responsibility

To pick a direction for #61 on whether we want to use predictable tags or use unique tags that require a tag listing to avoid race conditions, please vote on this issue. We'll leave this open for 1 week and move forward based on the results in the 2022-07-29 meeting. Vote by giving one of the below comments a thumbs up.

In follow up to #65

Please see conversation here #59 (comment)

Please adhere to the format of the template.

Primary contact: @sudo-bmitch

Proposal says:

Extend the Image Manifest with a refers field (existing registries should ignore this per OCI's extensibility requirement)

Why not also oci indexes?

Issue from WG meeting on Feb 8 2022: document our process for decision making and next steps.

Reading through the proposals, I believe that Proposal D is directionally the one that is best. I think this because it does not require changing the data model of registries which means that getting adoption will be easier.

Reading the meeting notes from when this proposal was reviewed, the issues identified appear to be:

1. Updating an OCI index is racy
2. Indexes are limited to 4 MB
3. Filtering cannot be done server side
4. Garbage collection needs to be done client side
5. There are use cases where people want to keep the digest the same but add metadata (signing?)

I believe that (1) is a real issue that the OCI should engage with. I can see arguments for either being explicit that registries are expected to be eventually consistent and clients must take this into account or providing some kind of transactional API for index manipulation.

(2) says to me that we should push people not to inline large blobs into OCI indexes. 4 MB should be enough to link objects together by reference (😅 I hope this doesn't come back to haunt me!).

I'm not sure I understand (3). If one wants to query a reference, they just need to fetch (by digest or have kept) the root OCI index. Registries could provide reverse lookup APIs (digest -> related objects) which are arguably no worse than the APIs proposed in Proposal E.

I'm not sure I understand (4). I would argue the opposite: Only Proposal D provides a working server-side GC model.

I've heard that there are use cases for keeping the digest of an object constant (5). I have not seen a concrete example so I don't understand it. It is by design that digests change when the content changes and tags are the current method of working around this.

Are these the only issues with Proposal D? I'd be happy to discuss others and to get more clarity on (5).

As per the WG discussion today (5/3/2022) there was agreement on the call to start to finalize any changes to prepare Proposal E for presentation to the OCI as the output "proposal" of this WG. Here are the points that we agreed on that need to happen in the meeting (please let me know if we need any changes):

• Update new manifest with example
  • Confirm if the new manifest could be the same as Proposal A rather than the few changes (Just need an explanation on why because they may be fine)
• Remove filtering from Proposal E completely
• Use distribution extensions for references HTTP API endpoint so that no changes to distribution-spec are required
• Add some context around upgrade path to new manifest for registry providers
• Making the upgrade path more clear regarding the end goal (added 6/28/22)

The following actions were also captured along side Proposal E to support the change:

• Clarify verbiage about specific and general concerns for changes to the image-spec

Description changelog

• Converted bulleted list to task list (lachie83)
• Checked task 2,3,4 (lachie83)
• Added task 5 upgrade path more clear to task list (lachie83)

This issue can be used to link all related PRs that action the list above.

Annotations
These annotations would be added for artifacts:

• org.opencontainers.artifact.type: type of artifact (sig, sbom, etc)
• org.opencontainers.artifact.description: human readable description for the artifact
• org.opencontainers.artifact.created: creation time for a manifest

Are these annotations required for the new artifact type?

Are these annotations valid to use on an image manifest?

There is nothing in the spec that says what registries need to do if you put in an artifact (I'm thinking about image indexes) that refers to a manifest that doesn't exist within the repository.

The options seem to be:

1. Registry refuses the artifact
2. Registry accepts the artifact, responds correctly to a call to the references API even if there is no manifest stored for the referenced digest

I'd like it if this spec were to make a call, even if that call is to write down that "The registry can decide the behaviour and both are valid options".

For garbage collection we do say this, but I'm really talking about tagged references:

For registries that implement garbage collection based on tagged manifests, an untagged manifest with a refers field pointing to an existing manifest should not be removed. When a manifest is deleted by a garbage collection policy or by an API request, all untagged artifacts that referred to that manifest may be cleaned by garbage collection.

As discussed on the working group Slack channel, I have some concerns with the current preferred proposal– Proposal E.

Things I'm concerned about in Proposal E (C1-3):

1. Adding another layer of object referencing (in addition to the existing OCI index/manifest list) to registries complicates the data model and GC.
2. Annotation filtering is an interesting feature (outside of just this work) but will be non-trivial for registries with large numbers of objects to add. I'd also be for doing this more generically rather than specifically for references.
3. The fallback of using tags as references will cause clutter on registries and require client side clean up as GCs currently preserve tagged items. Registries often have a repo tag limit (e.g.: ECR limits to 10k).

Questions I have (Q1-2):

1. How would one move an artifact and all its metadata from one registry to another?
2. What happens if the ecosystem does not broadly adopt the proposal and we're stuck in the fallback case?

For concerns (C1) and (C2), I think we need registry operators to chime in.

At a high level, I'm worried that requiring major changes to (properly) implement references will at best take a very long time to be adopted and at worst not be adopted broadly by the ecosystem.

From today's meeting, we wanted to have a vote on the direction for the working group so we can focus our attention on finishing one proposal that we'll present to the other parts of OCI. It seems like we are picking between E and F, so I'll add those two options below, but if others feel strongly for any of the other proposals, feel free to add a comment below to vote on. We'll leave this open until our next meeting on July 5th.

Please list here any concerns you would like to discuss relating to Proposal F

cc @SteveLasker

Voting seemed to work for picking a direction in this group, so here's a vote for #59. Should we move the annotation to be a first class type in artifact-spec and depend on the config media type in image-spec? Vote by giving a thumbs up to one of the two comments below. We'll leave this open for 1 week, and go with the community's decision on the 2022-07-19 meeting.

Considering unfinished discussion in #47 and #48, and also on the weekly call yesterday, the best path forward is to add another proposal (F) that addresses these concerns. Please see the template.

Without an alternative proposal to consider, the WG will continue to explore the feasibility of Proposal E, our "frankenstein / voltron" proposal that, to the best of our abilities, combines various good parts of proposals A-D.

Please let us know if we can expect to see this soon.

cc: Docker friends @chris-crone @tonistiigi @errordeveloper @justincormack

In the call today we discussed the registry-level searching, such as:

GET /v2/_oci/references?q_manifests__mediatype__contains=chocolate

The general consensus was that this is out of scope for the current iteration.

Once we have figured out the basics of how to store and relate things, this group (or a new WG) should address the concept of cross-repo searching and filtering.

Came up during the general call today-

• What parts are to be proposed in distribution-spec
• What parts are to be proposed in image-spec
• What parts are to be proposed in artifacts?
• Will we require a new repo (e.g. "artifact-spec") for the new manifest type?

Is this a recommendation that should from from the WG or TOB?

cc @SteveLasker @sajayantony @sudo-bmitch @mikebrow

Please adhere to the format of the template.

Primary contact: @nishakm

As discussed on the call, since upstream PRs have been opened (almost), does it make sense to archive this repo? Any changes to the proposal that deviate from the original proposal E can take place in the PRs