From 8258e546e2d00dcfe9f0b70893cc0deb4483fc42 Mon Sep 17 00:00:00 2001 From: Sajay Antony Date: Thu, 10 Aug 2023 22:47:57 +0000 Subject: [PATCH] simplify decision tree for artifacts Signed-off-by: Sajay Antony --- docs/concepts/artifact.mdx | 61 ++++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 19 deletions(-) diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx index e47d277d..eff9eb7c 100644 --- a/docs/concepts/artifact.mdx +++ b/docs/concepts/artifact.mdx @@ -64,8 +64,8 @@ flowchart TD B -->|No| E[type=manifest.config.mediaType] ``` -For aritifact authors, the the choice of whether to set the `artifactType` or -`config.mediaType` depends on the contents and shape of the artifact and is discussed in the following sections. +For aritifact authors, the sections below should help deciding on the blob and +config mediaTypes. ## Dissecting the Manifest @@ -110,10 +110,36 @@ in this case the config is an empty blob as per the [empty descriptor guidance][ ### Artifacts with config -Clients can use `config.mediaType` property to -declare the artifact type. The `config.mediaType` may be used when artifacts have a valid config blob and -the mediaType matches the config blob and type of the artifact. For example the -artifact type below for the helm chart is `application/vnd.cncf.helm.config.v1+json` +Clients have been using the `config.mediaType` property to declare the artifact type. +For OCI artifacts that have a valid config blob the config blob may use its own +mediaType and the `artifactType` property can be set to indicate the type of artifact. + +```json + { + "schemaVersion": 2, + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "artifactType": "application/vnd.example+type", + "config": { + "mediaType": "application/vnd.example.config.v1+json", + "digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03", + "size": 123 + }, + "layers": [ + { + "mediaType": "application/vnd.example.data.v1.tar+gzip", + "digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317", + "size": 1234 + } + ] + } +``` + +#### Prior Art + +Before version 1.1 of the [image specification][image-spec], the `config.mediaType` +was used to indicate the type of the artifact. +For example the artifact type below for the helm chart is `application/vnd.cncf.helm.config.v1+json` +as the manifest does not have the `artifactType` property. ```json { @@ -136,10 +162,10 @@ artifact type below for the helm chart is `application/vnd.cncf.helm.config.v1+j ### Annotations only artifacts -Artifacts may store metadata in the manifest as annotations and do not have a config or blobs. +Artifacts may store metadata in the manifest as annotations and need not have a config or blobs. For these the `artifactType` property is used to declare the type of the artifact. -The config property is required in the manifest for maximum compatiblity an empty layer is also created. -as per the [empty descriptors guidance][empty-descriptor]. +The config property is required in the manifest and for maximum compatiblity +an empty layer is also created as per the [empty descriptors guidance][empty-descriptor]. ```json { @@ -167,26 +193,22 @@ as per the [empty descriptors guidance][empty-descriptor]. ### Deciding on artifactType or config.mediaType -Considering the above types of artifacts, the decision tree below should help -determine what fields to set when creating an artifact. +Putting it all together with the types of artifacts listed above, the decision tree +below should help determine what fields to set when creating an artifact. ```mermaid graph TD HasBlob{Artifact has at least
one file or blob?} HasConfigData{Artifact has additional
metadata config blob?} - HasConfigEqArtifactType{Artifact has an artifactType
equal to the
the config blob mediaType?} - Artifact_NoBlobs[Specify artifactType,
set config and layers
to empty descriptors.] - Artifact_NoConfig[Specify artifactType, include
artifact in layers, set
config to empty descriptor.] - Artifact_WithConfigBlob[Specify artifactType to value,
specify config blob and mediaType,
include artifact in layers.] - Artifact_NoArtifactType[Specify config blob and it's mediaType
to indicate artifactType,
include artifact in layers,
do not set artifactType.] + Artifact_NoBlobs[Specify artifactType,
set config and layers
to empty descriptors.] + Artifact_NoConfig[Specify artifactType, include
artifact in layers, set
config to empty descriptor.] + Artifact_WithConfig[Specify artifactType,
specify config blob and mediaType,
include artifact in layers.] HasBlob -- No --> Artifact_NoBlobs HasBlob -- Yes --> HasConfigData + HasConfigData -- Yes --> Artifact_WithConfig HasConfigData -- No --> Artifact_NoConfig - HasConfigData -- Yes --> HasConfigEqArtifactType - HasConfigEqArtifactType -- Yes --> Artifact_NoArtifactType - HasConfigEqArtifactType -- No --> Artifact_WithConfigBlob ``` ### Harnessing Image Indexes @@ -231,6 +253,7 @@ specifications. [cas]: https://en.wikipedia.org/wiki/Content-addressable_storage [oci-layout]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-layout.md [descriptor]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/descriptor.md +[image-spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/spec.md [image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#image-manifest [image-properties]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#image-manifest-property-descriptions [empty-descriptor]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#guidance-for-an-empty-descriptor