Artifacts clarification

[neersighted]

• Closes Descriptors, the platform object, and the artifactType #1131
• Relates to Add clarifaction for WASM OCI artifact use case #1137
• Follow-up to Remove artifact manifest #999

Attempt to better clarify the conceptual differences between artifacts and images (which I tie to the config as described in this spec), and provide guidance on how to detect artifacts from code.

Also attempt to clarify how descriptors interact with artifacts in the aftermath of #999.

[tianon]

I haven't done a full review, but just noting some of my thoughts so far to hopefully spark more discussion.

[tianon]

As a runtime-spec maintainer also, I'm very confused by this block -- the config object holds the data used to construct a runtime-spec "bundle", but it is not parsed/specified as part of the runtime-spec. The two are very loosely related. 😅

[neersighted]

Yeah, I'm not quite 100% happy with this either, but there are other parts of the spec that allude to the runtime spec, and "config that is meant to construct a runtime spec config base" still is a useful distinction, I believe.

[jsturtevant]

This also seems at contradiction to the statement below: It is possible that software implementing the runtime-spec may also be able to interpret Artifacts; however that is outside the scope of this spec. Couldn't a runtime generate a runtime-spec based on something other than a classic image-config? The loose coupling seems like this would make this possible.

I am thinking eventually we will want a WASM Artifact that doesn't use the image config format but still gets converted to a runtime-spec for runtimes that support the artifact type.

[neersighted]

It definitely could; does anyone have suggestions on how to describe interpretation of the classical config.md config without muddying the waters with runtime-spec references?

[neersighted]

I think that referring to conversion.md and the mechanism therein is the clarification I want.

[tianon]

IMO we really can't get away from specifying that "images" have strict layer media type requirements too -- if a given runtime can't parse one of the layers, it can't reasonably assume it can (safely) do anything with the rest of that registry object (manifest, artifact, image, whatever you want to call it).

[neersighted]

I don't want to address that in this PR yet. As a follow-up to this, I want us to discuss rootfs vs non-rootfs layer types and how we can consistently decide which layers must be interpreted and which are "optional."

[sudo-bmitch]

I have a high level concern that we're trying to document the mixture of runnable Images and Artifacts in the same Index. Is that something we want to standardize in OCI, or would runtimes prefer that they are only asked to run an entry from an Index of only Images?

The concern I have is there's no limit to unique media types an Artifact may use, and there's likely a desire by new use cases to define new types of runnable content that may also have new media types that a current runtime would not have seen before. I'm wondering if we want to differentiate between a runtime unsure how to run the requested content vs a runtime not finding any Image content in an Index.

Feedback from @opencontainers/runtime-spec-maintainers is welcome.

[neersighted]

I have a high level concern that we're trying to document the mixture of runnable Images and Artifacts in the same Index. Is that something we want to standardize in OCI, or would runtimes prefer that they are only asked to run an entry from an Index of only Images?

Yes, this is a realistic use-case with inline metadata today, e.g. what BuildKit does.

I'm wondering if we want to differentiate between a runtime unsure how to run the requested content vs a runtime not finding any Image content in an Index.

I think this is behavior defined by the runtime; what I want to make clear is that a runtime can interpret new artifact types if it has explicit support for them. But the default should be "ignore any content I do not know how to interpret" to obviate the need for platform: unknown/unknown and similar hacks with regard to platform selection.

[sudo-bmitch]

I have a high level concern that we're trying to document the mixture of runnable Images and Artifacts in the same Index. Is that something we want to standardize in OCI, or would runtimes prefer that they are only asked to run an entry from an Index of only Images?

Yes, this is a realistic use-case with inline metadata today, e.g. what BuildKit does.

I want to be careful that we don't say "buildkit implemented it, therefore OCI needs to recommend it". It's not unlike how cosign pushed manifests that looked like an OCI image with a different layer type to get around registries that filtered unknown config mediaType values. Even though the behavior works and doesn't violate the spec, I'm not incline to recommend that as a method to push artifacts.

Before I weigh in on the mixed content in an Index scenario, I'd like to hear from the impacted users that would be parsing that content (runtime maintainers).

[jonboulle]

Suggested change

	Artifacts can be detected at runtime using by checking two keys:
	Artifacts can be detected at runtime by checking two keys:

[neersighted]

cc @dmcgowan re: runtime behavior with mixed indexes.

[jsturtevant]

Suggested change

	Conversely, an Artifact is any other conformant content that **does not contain a config to be interpreted by a runtime-spec implementation using the conversion mechanism.
	Conversely, an Artifact is any other conformant content that **does not** contain a [config](config.md) to be interpreted by a runtime-spec implementation using the conversion mechanism.

[sajayantony]

My understanding is that the wasm folks want to use the artifact type. It's runnable by the wasm runtime and not something that is aligned with the runtime spec.
How can we support them by enabling the usage of artifactType ? @cpuguy83 @tianon what do you folks think?

[neersighted]

That is covered by the case of "runtime has special knowledge of how to handle an artifact."

For the WASM-with-existing-containerd case, they should not set the artifact type as they will just be a "regular" image with special layers and a WASM platform object.

[sajayantony]

I’m probably at the risk of swimming against the current here but I honestly was hoping that the artifact type could be set by anyone and not limited to.
if the OCI runtime spec doesn’t want the artifact type set then it can mandate that but WASM runtimes don’t need to honor that.

[neersighted]

The issue is that I need a way to tell "not runnable" from "runnable" in containerd; I'd rather not have "an image" that is also "an artifact" at the same time as we get back to the platform: none/none pattern.

[neersighted]

cc @jsturtevant; this is meant to enable (through clarity of what runtimes likely SHOULD support) efforts to make "native WASM images" work with "existing runtimes;" I see no reason that something that is otherwise a conformant image (and just uses a wasm platform) needs to set artifactType.

This is also somewhat related to #1141 (comment), which I still want to keep as a follow-up as the scope of this PR has grown quite a bit.

[jsturtevant]

I see no reason that something that is otherwise a conformant image (and just uses a wasm platform) needs to set artifactType.

As we've been using it without artifactType, we've found it is difficult to differentiate between "wasm oci image" (with custom layers) and standard images. This was one of the reasons we initially included ArtifactType, it was a way to signify that the image has non-standard layers in it. It is additional steps to look up the config media type, open it up and look at the platform.

The Wasm OCI image agreed on is special due to the additional layers, but there isn't really a great way to determine that via the manifest (without iterating through layers or looking up the platform on the config). Is it possible to set the ArtifactType and have the config.mediaType be the standard image media type? It would still allow runtimes to reject artifact types since artifact is set?

[neersighted]

It's certainly possible; as discussed on the last PR having the standard config mediaType with a custom artifactType is rather outside what most would consider idiomatic, however.

The platform field on the descriptor should be the same as the platform in the config blob, so the platform of the image should be accessible via the same mechanism as the top-level artifactType.

Additionally, I do think that an annotation with e.g. "WASM image standard version" or similar would be perfectly idiomatic if you need some additional metadata.

WDYT?

[mikebrow]

see comments...

[mikebrow]

not nec. to rescope the image spec from inside this sub-doc...

[mikebrow]

Suggested change

	Both are representing using a [manifest](manifest.md).
	Artifacts may be represented using an [image manifest](manifest.md).

This sentence repeats the one this commit moves down... maybe just add the missing link to the prior original block?

[mikebrow]

This is probably the wrong place to define what an image is..

[neersighted]

It's being defined in contrast to Artifacts for now... I think it's okay; this isn't the best place to have this long-term, but for now this seems like a relevant place to try and explain what the difference between an image and an artifact is.

[mikebrow]

fair..

Suggested change

	Images are defined in this specification as conformant content with a conformant [config](config.md), processed according to [conversion.md](conversion.md) to derive a [runtime-spec][] configuration blob.
	Images having conformant content with conformant [config](config.md) are processed according to [conversion.md](conversion.md) to derive a [runtime-spec][] configuration blob.

[mikebrow]

This definition appears to be in conflict with the current guidelines https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage or at least is a further restriction that probably should be defined in the above link

[mikebrow]

What do you mean by ignore here?

Probably best to direct new conversion SHOULD language to conversion.md?

[cpuguy83]

This kind of makes sense, but also today no runtime ignores unknown artifact types because they aren't aware of the field since it is completely new.

[neersighted]

Yeah, this is somewhat of a new behavior, but at the same time is just an attempt to suggest what seems the only sane default. The idea here is that tools like BuildKit could stop producing platform: unknown/unknown to prevent their not-images from being considered for platform selection by simply switching to artifacts instead.

[cpuguy83]

The issue here is not specifying a garbage platform will cause older implementations to blow up.
I'm not sure what that means for the wording here.
Putting anything in an index that is not an image manifest is not backwards compatible, I guess.

[neersighted]

Most tools should ignore artifacts already (but not as eagerly/not as codified as I'd like) by virtue of e.g. the config mediaType or the layer types, thankfully. See #1131 (comment) for some research into this (though I could definitely do more testing with existing implementations and mixed indexes).

[cpuguy83]

I guess in this case the artifact type should be listed below valid runtime image manifests?

[mikebrow]

Suggested change

	It is possible that implementations may also be able to interpret known Artifact types; however that is outside the scope of this spec.
	Interpretation / implementation of known Artifact types is currently outside the scope of this spec.

[rchincha]

Can the phrase "known Artifact" be clarified here?
Does it mean artifactType field exists or not?
Does it mean artifactType field exists but uses a well-known media-type?
Does it mean well-known media-type to outside world but not to this spec?
etc ... etc ...

[mikebrow]

Suggested change

	Artifacts can be detected at runtime using by checking two keys:
	Artifacts can be detected at runtime by checking two key-value fields:

[mikebrow]

Suggested change

	1. Is an `artifactType` present in the descriptor, or in the [manifest](manifest.md)?
	1. Is an {`artifactType`, _string_} present, e.g. as a `subject` reference in an image/artifact manifest or as a self reference definition in the [image artifact manifest `artifactType` field](https://github.com/opencontainers/image-spec/blob/main/manifest.md#image-manifest-property-descriptions)?

[mikebrow]

seems like that's 3 keys.?

probably a good idea to explain here, not following the if the config.mediaType is unknown it's an artifact thought..

[rchincha]

Now that image-spec and dist-spec officially have "artifact" support, perhaps revisit this? converging to config.mediaType=empty and basically only do 1. above?

[mikebrow]

Sure I see now what @neersighted meant.

Proposed text:

An oci image manifest can be identified as an artifact of some type other than known oci container image type by 1) first checking if the artifact type value is set and if so whether it is valid by RFC6838, 2) otherwise checking if the config mediaType value is not one of the known OCI Image Types and is valid by RFC6838.

Proposed pseudo explanation:

func checkForArtifactType(manifest) artifactType, error 
{
manifestArtifactTypeMustBeSet = UNKNOWN
manifestArtifactTypeIsSet = UNKNOWN
manifestArtifactTypeMustBeValid = UNKNOWN
manifestArtifactTypeIsValid = UNKNOWN
configMediaTypeIsOCIImageType = UNKNOWN
configMediaTypeIsValidArtifact = UNKNOWN

if manifest.config.mediaType is "application/vnd.oci.empty.v1+json" { 
   manifestArtifactTypeMustBeSet = TRUE;
}

manifestArtifactTypeIsSet = is manifest.artifactType unset or nil? 

if manifestArtifactTypeIsSet {
   manifestArtifactTypeMustBeValid = TRUE;
}

if manifestArtifactTypeMustBeValid {
   manifestArtifactTypeIsValid = checkRFC6838(manifest.artifactType);
   if !manifestArtifactTypeIsValid {
      return with error(manifest.artifactType + "is not valid")
   }
   return manifest.artifactType // we have the artifact type we were looking for
}

configMediaTypeIsOCIImageType = isKnownOCIImageConfigMediaType(manifest.config.mediaType)

if configMediaTypeIsOCIImageType { 
   return image .. no artifact found
}

// not "oci.empty" and not an oci image media type
configMediaTypeIsValidArtifact = checkRFC6838(manifest.config.mediaType);

if !configMediaTypeIsValidArtifact {
   return with error(manifest.config.mediaType + "is not valid") 
}

return manifest.config.mediaType // we have the artifact config media type we were looking for
} // end checkForArtifactType()

func checkRFC6838 (type string) BOOL 
{
  // returns true if not nil and complies with [RFC 6838](https://tools.ietf.org/html/rfc6838), including the [naming requirements in its section 4.2](https://tools.ietf.org/html/rfc6838#section-4.2)
}

[rchincha]

This would be a nice subroutine to add to this repo - likely to be heavily used going forward.

1. Runnable container images
2. Non-runnable not-container images (referrer or otherwise)
3. Runnable non-container images

^ if I were to summarize.

[rchincha]

Just a thought ... OCI = packaging + distribution + "bring your own runtime (BYOR)"?

[sudo-bmitch]

Given the various scenarios we're seeing, and knowing there will be more scenarios in the future, perhaps instead of being prescriptive in exactly what fields are defined and we should keep it at a higher level. Something like "container images are any content pushed to the registry designed to be executed by a container runtime, artifacts are everything else."

There will be artifacts that want to have a valid platform defined, and other artifacts that want to use the image config media type. We may be able to avoid the latter with guidance in the spec, but that value isn't visible in the Index. And expecting runtimes to avoid trying to run an artifact image based on a new field in the descriptor (i.e. artifactType) is going to be error prone for existing runtimes that aren't aware of new fields.

The two options I can think of are either to ensure artifacts are listed after any container images in an index, so that the selector for container runtimes selects the first match, or OCI recommends against mixing container images and artifacts in the same index for the best support of older runtimes.

[sudo-bmitch]

Why would we prohibit container runtimes, and their fat clients, from executing/processing artifacts?

My phrasing is that container runtimes trying to execute/process it makes it a container image. It's not restricting what runtimes can do, it's defining whether it's a container image or artifact based on whether runtimes could execute/process it. It leaves flexibility for runtimes to extend to process more content in the future without us needing to adjust the image-spec for every runtime change.

[mikebrow]

Given the various scenarios we're seeing, and knowing there will be more scenarios in the future, perhaps instead of being prescriptive in exactly what fields are defined and we should keep it at a higher level. Something like "container images are any content pushed to the registry designed to be executed by a container runtime, artifacts are everything else."

There will be artifacts that want to have a valid platform defined, and other artifacts that want to use the image config media type. We may be able to avoid the latter with guidance in the spec, but that value isn't visible in the Index. And expecting runtimes to avoid trying to run an artifact image based on a new field in the descriptor (i.e. artifactType) is going to be error prone for existing runtimes that aren't aware of new fields.

The two options I can think of are either to ensure artifacts are listed after any container images in an index, so that the selector for container runtimes selects the first match, or OCI recommends against mixing container images and artifacts in the same index for the best support of older runtimes.

IMO it is not a good idea to redefine (is/are language) what a container image is inside the artifacts guidance documentation.

Let's not leave out the index may or may not include platform filters, and "implementations SHOULD support" "application/vnd.oci.image.index.v1+json (nested index)" and "an encountered mediaType that is unknown to the implementation MUST NOT generate an error."

[mikebrow]

My phrasing is that container runtimes trying to execute/process it makes it a container image. It's not restricting what runtimes can do, it's defining whether it's a container image or artifact based on whether runtimes could execute/process it. It leaves flexibility for runtimes to extend to process more content in the future without us needing to adjust the image-spec for every runtime change.

I think it's an oci container image if it's in a format conforming to the image spec for storage or transport, and then at runtime, by conversion and augmentation via a container runtime, if it is determined by a runc compatible runtime to then adhere to the runtime spec config and rootfs requirements of a runtime bundle for a platform.

[mikebrow]

artifacts are a grey space wrt. whether they can be considered a part of or augmentation to layers/config/index, guidance, filtering mechanisms, additional image config, even possibly a key store, alg, or content for a new digest type... runnable or not is probably up to the iana type or we possibly break with existing spec restrictions.

100% agree we need to avoid a client reading an artifact, via matching, as a default platform image if/when that is not the intended result.

[mikebrow]

I like the high level definition here: https://github.com/opencontainers/image-spec/blob/main/spec.md#overview

At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more filesystem layer changeset archives that will be unpacked to make up the final runnable filesystem. The image configuration includes information such as application arguments, environments, etc. The image index is a higher-level manifest which points to a list of manifests and descriptors. Typically, these manifests may provide different implementations of the image, possibly varying by platform or other attributes.

[sudo-bmitch]

Let's not leave out the index may or may not include platform filters, and "implementations SHOULD support" "application/vnd.oci.image.index.v1+json (nested index)" and "an encountered mediaType that is unknown to the implementation MUST NOT generate an error."

An issue attempting to be solved in this PR is runtimes picking container images from a mixed index with artifacts included in the manifest list. The artifact entries could have matching platform values, and known media type values. My comments above are looking at what options, if any, we have to resolve that. I don't believe "MUST NOT generate an error" helps in this scenario since the values would be known.

[mikebrow]

An issue attempting to be solved in this PR is runtimes picking container images from a mixed index with artifacts included in the manifest list. The artifact entries could have matching platform values, and known media type values. My comments above are looking at what options, if any, we have to resolve that. I don't believe "MUST NOT generate an error" helps in this scenario since the values would be known.

absolutely... 100% agree we need to avoid a client reading an artifact, via matching, as a default platform image if/when that is not the intended result.

my point in including the additional cites was as a reminder:

1. that said artifacts might be in a nested index vs.. the platform index..
2. if the manifest type is unknown it must not generate an error...

and those current rules may be useful in finding a resolution..

For example, a) push said artifacts into an index under the platform index... (and check if clients actually recurse today for nested indexes... suggesting a solution here where platform (optional) "index" is for container image manifests and nested indexes not for artifact type manifests irregardless of the desire to filter artifacts by platform
b) add a new manifest type for an artifact index, allowing platform (optional) "index" to have nested platform (optional) "indexes" and platform (optional) "artifact indexes", and the new "artifact index" would be a child of another index and contain further artifact indexes and image manifest with an artifact type.

Dropping my block since no runtime maintainer have expressed any concerns.

[sudo-bmitch]

Suggested change

	Content other than Images MAY be packaged using the [manifest]; this is otherwise known as an Artifact.
	Content other than Images MAY be packaged using the [manifest](manifest.md); this is otherwise known as an Artifact.