Define image manifest artifactType and guidance#1043
Define image manifest artifactType and guidance#1043sudo-bmitch merged 1 commit intoopencontainers:mainfrom
Conversation
aab8d56 to
f6212d6
Compare
sajayantony
left a comment
There was a problem hiding this comment.
Overall, there seemed to be consensus on the call and a desire to move forward with artifactType being defined in the image manifest so that referrers can release.
I would love for OCI to remove the requirements for Layers clearer in 2.0. But that is for another day.
f6212d6 to
695b425
Compare
| ```json,title=Artifact%20with%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson | ||
| { | ||
| "schemaVersion": 2, | ||
| "mediaType": "application/vnd.oci.image.manifest.v1+json", |
There was a problem hiding this comment.
should we add artifactType here..
There was a problem hiding this comment.
When config.mediaType is defined to something other than scratch, artifactType is optional.
There was a problem hiding this comment.
To be slightly prescriptive about best practices, should we say that non-image artifacts SHOULD use an artifactType with the scratch config?
Not a MUST.
There was a problem hiding this comment.
@AaronFriel I'm open to it, but in case there are other opinions, how about we make that a separate PR. Would you like to lead that?
695b425 to
7ca9ebc
Compare
| When this is done, the `config.mediaType` value MUST be set to a value specific to the artifact type or the [scratch value](#example-of-a-scratch-config-or-layer-descriptor). | ||
| If the `config.mediaType` is set to the scratch value, the `artifactType` MUST be defined. | ||
| If the artifact does not need layers, a single layer SHOULD be included with a non-zero size. |
There was a problem hiding this comment.
I am not sure if it was part of the discussion I missed (but even if so, I think the explanation should stand here alone): why would I choose to use scratch+artifactType, rather than just setting config.mediaType to whatever specific value I want to use?
There was a problem hiding this comment.
I expect any artifact producing implementation that doesn't need or want a config will use a scratch manifest.
Suppose you just want to upload an SBOM, or a cat gif (image/gif). What do you put in config.mediaType?
If you chose image/gif, some implementations might try to render the config as a gif, or save it as a .gif file on download, etc. The config descriptor however won't point to a gif blob, it'll point to {} and the first layer will be the image/gif.
There was a problem hiding this comment.
@jonboulle the issue that was raised is the config.mediaType must reference the content of the config.digest blob according to the descriptor spec. By using that for artifacts that do not have a dedicated config blob, we have a mismatch between the media type of the blob and the artifactType of the artifact.
There was a problem hiding this comment.
Sorry, I might have asked the question backwards :)
In what circumstance would I set config.mediaType to something other than scratch or an actual (``application/vnd.oci.image.config.v1+json`) config? Is there a use case there we really need to support?
There was a problem hiding this comment.
There are actual configs that are not application/vnd.oci.image.config.v1+json, e.g. Helm charts and Singularity images. These use cases are following the guidance at https://github.com/opencontainers/artifacts/blob/main/artifact-authors.md. My goal was to avoid breaking those existing artifacts unless there's a strong need to do so.
There was a problem hiding this comment.
Thanks, that's the exact reference that was missing for me. I will think about it for another moment; I would rather it's captured more explicitly here
|
Hi all, I have some questions on how the Given this PR, I would expect In the server reply the Also if this is the case, I would expect the It doesn't seem consistent for the consumer of the API. |
|
@andaaron the update to the referrers API is in distribution-spec: opencontainers/distribution-spec#395 |
Signed-off-by: Brandon Mitchell <git@bmitch.net>
7ca9ebc to
23c4647
Compare
sajayantony
left a comment
There was a problem hiding this comment.
We can add the the case for helm or backwards as per @jonboulle comment as a follow up if needed
tianon
left a comment
There was a problem hiding this comment.
In jq, this means consumers looking to query artifactType should use an expression something like .artifactType // .config.mediaType, but the benefit is that it allows the config blob's descriptor to be "pure" and actually describe the blob it points to instead of the object it's part of, so I'm in favor.
This adds an
artifactTypefield in the image manifest, defines a scratch media type, and provides guidance on using the image manifest for artifacts. This design is based on the discussions from the 2023-03-23 meeting.