add concept for OCI Artifact (#238)

Signed-off-by: Sajay Antony <[email protected]>
Co-authored-by: Shiwei Zhang <[email protected]>

docs/concepts/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Concepts",
+    "position": 50,
+    "link": {
+        "type": "generated-index",
+        "description": "Concepts"
+    }
+}

docs/concepts/artifact.mdx

@@ -0,0 +1,237 @@
+---
+title: OCI artifact
+sidebar_position: 1
+---
+
+# Understanding OCI artifacts
+
+The Open Container Initiative (OCI) organization has played
+a crucial role in defining the industry-standard specifications for container
+formats, runtime, and artifacts.
+OCI artifacts encompass an extensive variety of content types, from signatures,
+Software Bill of Materials (SBOMs), Helm charts, container images, to Open Policy Agent (OPA)
+bundles and more, thereby lending incredible flexibility to how containerized
+applications are packaged, delivered, and updated.
+
+This article will delve into OCI artifacts created using a manifest defined as a part of
+the OCI image specification.
+
+## The Anatomy of an OCI artifact
+
+The structure of an OCI Artifact includes an Image Manifest or an Image Index
+that points to other OCI artifacts. These artifacts can be stored and accessed from
+[content addressable storage][cas] like a registry, or an on-disk storage like
+an [OCI-Layout][oci-layout] directory.
+
+The OCI artifact can be referenced using a *tag*
+or a *digest*. The digest is a hash of the OCI artifact manifest or index and
+should be assumed to be immutable where as the tag may be mutable.
+
+A *tag* resolves to a data structure called the [descriptor][descriptor] which
+contains the digest of the manifest or index.
+
+![Diagram showing relationship and fiels of a tag image and index](/img/concepts/artifact/tag_relations.png)
+
+### The Significance of Annotations
+
+Annotations in OCI artifacts offer a means of adding metadata to various
+components, including the Image Manifest, Image Index and Image Layers.
+These annotations hold key-value pairs that represent either the metadata
+of the OCI artifact or blobs, such as the creation time, or data of the artifact itself.
+
+```json
+{
+  ...
+  "annotations": {
+    "oci.opencontainers.image.created": "2023-01-02T03:04:05Z",
+    "com.example.information": "useful-info"
+  }
+}
+```
+
+### Determining the artifact type
+
+For OCI artifacts the **type** of the artifact may be determined from the `artifactType` property
+in the image manifest or index. This property was introduced in v1.1 of the [image specification][image-properties].
+
+In cases when the `artifactType` property is not defined, the `config.mediaType` property may be used to determine
+the type of the artifact as shown in the diagram below.
+
+```mermaid
+flowchart TD
+    B{Is\nmanifest.artifactType\ndefined?}
+    B -->|Yes| C[type=manifest.artifactType]
+    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.
+
+## Dissecting the Manifest
+
+The structure of the artifact depends on the purpose of the artifact and content.
+The manifest is a JSON document that contains the metadata for the artifact.
+Artifacts may have files that are stored as blobs or metadata that is stored in the manifest
+as annotations. The manifest may also contain references to other artifacts.
+
+### Artifacts with blobs
+
+Let's delve into an OCI artifact that uses an [Image Manifest][image-manifest].
+Below is an example where artifact type is `application/vnd.example+type`. The artifact
+also has blobs that are referenced in the manifest in the `layers` property. It is
+important to note that the `config` property is required in the manifest and
+in this case the config is an empty blob as per the [empty descriptor guidance][empty-descriptor].
+
+```json
+ {
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "artifactType": "application/vnd.example+type",
+  "config": {
+    "mediaType": "application/vnd.oci.empty.v1+json",
+    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+    "size": 2
+  },
+  "layers": [
+    {
+      "mediaType": "application/vnd.oci.image.layer.v1.tar",
+      "digest": "sha256:d2a84f4b8b650937ec8f73cd8be2c74add5a911ba64df27458ed8229da804a26",
+      "size": 12,
+      "annotations": {
+        "org.opencontainers.image.title": "hello.txt"
+      }
+    }
+  ],
+  "annotations": {
+    "org.opencontainers.image.created": "2023-08-03T00:21:51Z"
+  }
+}
+```
+
+### 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`
+
+```json
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "config": {
+    "mediaType": "application/vnd.cncf.helm.config.v1+json",
+    "digest": "sha256:34bf03806938a59ee7dc3e2c33e314d0eaef573313ff9dcc677113502d568523",
+    "size": 145
+  },
+  "layers": [
+    {
+      "mediaType": "application/vnd.cncf.helm.chart.content.v1.tar+gzip",
+      "digest": "sha256:4d80464e9d8e9f3ba92e6ead6d3b5afd0532cb0a81e980599a0bced99fdc6e01",
+      "size": 3763
+    }
+  ]
+}
+```
+
+### Annotations only artifacts
+
+Artifacts may store metadata in the manifest as annotations and do 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].  
+
+```json
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "artifactType": "application/vnd.example+type",
+  "config": {
+    "mediaType": "application/vnd.oci.empty.v1+json",
+    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+    "size": 2
+  },
+  "layers": [
+    {
+      "mediaType": "application/vnd.oci.empty.v1+json",
+      "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+      "size": 2
+    }
+  ],
+  "annotations": {
+    "oci.opencontainers.image.created": "2023-01-02T03:04:05Z",
+    "com.example.info": "useful-info"
+  }
+}
+```
+
+### 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.
+
+```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
+```
+
+### Harnessing Image Indexes
+
+One of the key advantages of OCI artifacts is their ability to utilize [Image Indexes][image-index],
+allowing the bundling of various OCI artifacts.
+
+The Image Index is a higher-level construct in the OCI Image Specification that can point to
+multiple Image Manifests, each suitable for a different platform or architecture or filtered by annotation.
+It helps to group related artifacts together, providing a single entry-point for accessing any specific
+artifact depending on the required condition.
+
+## Best Practices and Limitations
+
+While working with OCI artifacts, keep in mind that client tools and registries
+are in the process of implementiong v1.1 version of the OCI image and distribution specifications.
+
+- When clients or registries support the `artifactType` property, the `config.mediaType`
+can be set to _application/vnd.oci.empty.v1+json_ if the artifact doesn't have a config.
+blob as per the [empty descriptor guidance][empty-descriptor].
+- As a rule of thumb, keep the manifest size manageable by avoiding excessive annotations
+and leveraging blobs for larger data chunks.
+
+## The Road Ahead
+
+The evolution of OCI artifacts is a journey in progress. While the current specification
+does not permit an empty config blob, it's plausible that future updates might
+make config and blobs optional eliminating the need for the empty blob.
+
+By understanding OCI artifacts and their role in representing
+container images, developers and DevOps teams can ensure the smooth deployment
+and execution of containerized applications. The open and standardized nature of
+OCI artifacts promotes interoperability among different clouds and platforms,
+enabling seamless container orchestration and scaling across cloud and
+on-premises infrastructures.
+
+To learn more about the OCI Image Specification and Image Manifests, you can
+refer to the official [OCI Image Specification GitHub repository](
+https://github.com/opencontainers/image-spec) and explore the detailed
+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-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

docs/concepts/tag_relations.dot

@@ -0,0 +1,66 @@
+# To generate the image used, run the following command
+# dot -Tpng -o tag_relations.png tag_relations.dot
+digraph git_basics {
+	graph [
+        dpi=600
+		fontname = "Helvetica,Arial,sans-serif"
+	]
+	node [
+		style=filled
+		pencolor="#00000044" // frames color
+		fontname="Helvetica,Arial,sans-serif"
+        penwidth=1
+	]
+	edge [
+		arrowsize=0.5
+		labelfontcolor="#00000080"
+		penwidth=2
+	]
+
+    tag [
+		label=<<b>Tag</b>>
+		shape=box
+		color=lightcyan4
+		fillcolor=lightcyan1
+    ]
+
+    subgraph manifests {
+        rank=same
+        manifest [
+            color="#88000022"
+            shape=plain
+            label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                <tr> <td> <b>Manifest</b> </td> </tr>
+                    <tr> <td align="left">schema : <i>string</i><br align="left"/></td></tr>
+                    <tr> <td align="left">artifactType : <i>string</i><br align="left"/></td></tr>
+                    <tr> <td align="left">config : <i>descriptor</i><br align="left"/></td></tr>
+                    <tr> <td align="left">annotations : <i>map[string]string</i><br align="left"/></td></tr>
+                    <tr> <td align="left">subject : <i>descriptor</i><br align="left"/></td></tr>
+            </table>>
+        ]
+
+        index [
+            shape=plain
+            color="#88000022"
+            label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                <tr> <td> <b>Index</b> </td> </tr>
+                    <tr> <td align="left">manifests : <i>[ ]descriptor</i><br align="left"/></td></tr>
+            </table>>
+        ]
+    }
+
+	blobs [
+		fillcolor="#88ff0022"
+		label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+			<tr> <td  > <b>Blobs</b></td> </tr>
+			<tr> <td  align="left">config blob</td> </tr>
+            <tr> <td  align="left">layer blobs</td> </tr>
+            <tr> <td align="center">...</td> </tr>
+		</table>>
+		shape=plain
+	]
+
+    tag -> manifest
+    tag -> index -> manifest
+	manifest -> blobs 
+}

docusaurus.config.js

@@ -200,6 +200,10 @@ const config = {
         darkTheme: darkCodeTheme,
       },
     }),
+  markdown: {
+    mermaid: true,
+  },
+  themes: ['@docusaurus/theme-mermaid'],
 };
 
 module.exports = config;