Define image manifest artifactType and guidance #1043
Conversation
sudo-bmitch
requested review from
jonjohnsonjr,
jonboulle,
stevvooe,
sajayantony,
vbatts and
cyphar
as code owners
sudo-bmitch
force-pushed
the
pr-artifact-type
branch
from
aab8d56
to
f6212d6
Compare
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.
sudo-bmitch
force-pushed
the
pr-artifact-type
branch
from
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?
sudo-bmitch
force-pushed
the
pr-artifact-type
branch
from
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>
sudo-bmitch
force-pushed
the
pr-artifact-type
branch
from
7ca9ebc
to
23c4647
Compare
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
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.