From 8258e546e2d00dcfe9f0b70893cc0deb4483fc42 Mon Sep 17 00:00:00 2001 From: Sajay Antony Date: Thu, 10 Aug 2023 22:47:57 +0000 Subject: [PATCH 1/6] 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 From 2378da6abb1826010a1f0576bf9c4baff48018ef Mon Sep 17 00:00:00 2001 From: Sajay Antony Date: Fri, 11 Aug 2023 09:37:28 -0700 Subject: [PATCH 2/6] Update docs/concepts/artifact.mdx Co-authored-by: Billy Zha Signed-off-by: Sajay Antony --- docs/concepts/artifact.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx index eff9eb7c..d9bd5cde 100644 --- a/docs/concepts/artifact.mdx +++ b/docs/concepts/artifact.mdx @@ -64,7 +64,7 @@ flowchart TD B -->|No| E[type=manifest.config.mediaType] ``` -For aritifact authors, the sections below should help deciding on the blob and +For artifact authors, the sections below should help deciding on the blob and config mediaTypes. ## Dissecting the Manifest From eb034df103217f9914ee260ca690368884c12757 Mon Sep 17 00:00:00 2001 From: Sajay Antony Date: Fri, 11 Aug 2023 09:37:41 -0700 Subject: [PATCH 3/6] Update docs/concepts/artifact.mdx Co-authored-by: Billy Zha Signed-off-by: Sajay Antony --- docs/concepts/artifact.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx index d9bd5cde..137b0e2a 100644 --- a/docs/concepts/artifact.mdx +++ b/docs/concepts/artifact.mdx @@ -164,7 +164,7 @@ as the manifest does not have the `artifactType` property. 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 and for maximum compatiblity +The config property is required in the manifest and for maximum compatibility an empty layer is also created as per the [empty descriptors guidance][empty-descriptor]. ```json From 3a234afb5c1379a2b339fb48038e81d1fbfac398 Mon Sep 17 00:00:00 2001 From: Sajay Antony Date: Fri, 11 Aug 2023 17:25:52 +0000 Subject: [PATCH 4/6] addressed more PR feedback Signed-off-by: Sajay Antony --- docs/concepts/artifact.mdx | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx index 137b0e2a..06243f29 100644 --- a/docs/concepts/artifact.mdx +++ b/docs/concepts/artifact.mdx @@ -193,22 +193,23 @@ an empty layer is also created as per the [empty descriptors guidance][empty-de ### Deciding on artifactType or config.mediaType -Putting it all together with the types of artifacts listed above, the decision tree +Putting it all together with the types of artifacts listed above and +[Artifact Guidance in the image specification][artifact-guidelines], 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?} - - 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 +flowchart TD + HasBlob{Artifact has
at least one file?} + HasConfigData{Artifact has additional
metadata config blob?} + + Artifact_NoBlobs[Specify artifactType,
set config and layers
to empty descriptors.] + Artifact_NoConfig[Specify artifactType,
set config to empty descriptor,
include file in layers, ] + Artifact_WithConfig[Specify artifactType,
specify config blob and mediaType,
include files in layers.] + + HasBlob -- No --> Artifact_NoBlobs + HasBlob -- Yes --> HasConfigData + HasConfigData -- Yes --> Artifact_WithConfig + HasConfigData -- No --> Artifact_NoConfig ``` ### Harnessing Image Indexes @@ -258,3 +259,4 @@ specifications. [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 [image-index]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-index.md#image-index-property-descriptions +[artifact-guidelines]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#guidelines-for-artifact-usage \ No newline at end of file From 9aa20954b20002c7a4d9d7d54b4df9f8d04fc483 Mon Sep 17 00:00:00 2001 From: Sajay Antony Date: Sat, 12 Aug 2023 08:19:56 +0000 Subject: [PATCH 5/6] PR feedback Signed-off-by: Sajay Antony --- docs/concepts/artifact.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx index 06243f29..c27e840c 100644 --- a/docs/concepts/artifact.mdx +++ b/docs/concepts/artifact.mdx @@ -191,7 +191,7 @@ an empty layer is also created as per the [empty descriptors guidance][empty-de } ``` -### Deciding on artifactType or config.mediaType +### Arifact authoring decision tree Putting it all together with the types of artifacts listed above and [Artifact Guidance in the image specification][artifact-guidelines], the decision tree From b381d9ef98efc83188763d82735d4dca8f72e284 Mon Sep 17 00:00:00 2001 From: Sajay Antony Date: Tue, 15 Aug 2023 08:57:35 -0700 Subject: [PATCH 6/6] Update docs/concepts/artifact.mdx Co-authored-by: Shiwei Zhang Signed-off-by: Sajay Antony --- docs/concepts/artifact.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx index c27e840c..ed98df7d 100644 --- a/docs/concepts/artifact.mdx +++ b/docs/concepts/artifact.mdx @@ -259,4 +259,4 @@ specifications. [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 [image-index]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/image-index.md#image-index-property-descriptions -[artifact-guidelines]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#guidelines-for-artifact-usage \ No newline at end of file +[artifact-guidelines]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/manifest.md#guidelines-for-artifact-usage \ No newline at end of file