Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

simplify decision tree for artifacts #248

Merged
merged 6 commits into from
Aug 16, 2023
Merged

simplify decision tree for artifacts #248

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8258e54
simplify decision tree for artifacts
sajayantony Aug 10, 2023
2378da6
Update docs/concepts/artifact.mdx
sajayantony Aug 11, 2023
eb034df
Update docs/concepts/artifact.mdx
sajayantony Aug 11, 2023
3a234af
addressed more PR feedback
sajayantony Aug 11, 2023
9aa2095
PR feedback
sajayantony Aug 12, 2023
b381d9e
Update docs/concepts/artifact.mdx
sajayantony Aug 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 53 additions & 28 deletions docs/concepts/artifact.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 artifact authors, the sections below should help deciding on the blob and
config mediaTypes.

## Dissecting the Manifest

Expand Down Expand Up @@ -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
}
]
}
sajayantony marked this conversation as resolved.
Show resolved Hide resolved
```

#### 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
{
Expand All @@ -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 compatibility
an empty layer is also created as per the [empty descriptors guidance][empty-descriptor].

```json
{
Expand All @@ -165,28 +191,25 @@ as per the [empty descriptors guidance][empty-descriptor].
}
```

### Deciding on artifactType or config.mediaType
### Arifact authoring decision tree

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 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<br>one file or blob?}
HasConfigData{Artifact has additional<br> metadata config blob?}
HasConfigEqArtifactType{Artifact has an artifactType<br>equal to the <br>the config blob mediaType?}

Artifact_NoBlobs[Specify artifactType,<br>set config and layers<br>to empty descriptors.]
Artifact_NoConfig[Specify artifactType, include<br>artifact in layers, set<br>config to empty descriptor.]
Artifact_WithConfigBlob[Specify artifactType to value,<br> specify config blob and mediaType,<br> include artifact in layers.]
Artifact_NoArtifactType[Specify config blob and it's mediaType<br>to indicate artifactType,<br>include artifact in layers,<br>do not set artifactType.]

HasBlob -- No --> Artifact_NoBlobs
HasBlob -- Yes --> HasConfigData
HasConfigData -- No --> Artifact_NoConfig
HasConfigData -- Yes --> HasConfigEqArtifactType
HasConfigEqArtifactType -- Yes --> Artifact_NoArtifactType
HasConfigEqArtifactType -- No --> Artifact_WithConfigBlob
flowchart TD
HasBlob{Artifact has<br>at least one file?}
HasConfigData{Artifact has additional<br> metadata config blob?}

Artifact_NoBlobs[Specify <b>artifactType</b>,<br>set config and layers<br>to empty descriptors.]
Artifact_NoConfig[Specify <b>artifactType</b>,<br>set config to empty descriptor,<br>include file in layers, ]
Artifact_WithConfig[Specify <b>artifactType</b>,<br> specify config blob and mediaType,<br> include files in layers.]

HasBlob -- No --> Artifact_NoBlobs
HasBlob -- Yes --> HasConfigData
HasConfigData -- Yes --> Artifact_WithConfig
HasConfigData -- No --> Artifact_NoConfig
```

### Harnessing Image Indexes
Expand Down Expand Up @@ -231,7 +254,9 @@ 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
[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