add concept for ref types

Signed-off-by: Sajay Antony <sajaya@microsoft.com>
oras-project · Aug 9, 2023 · f50ff7e · f50ff7e
1 parent cf5a252
commit f50ff7e
Show file tree

Hide file tree

Showing 3 changed files with 278 additions and 0 deletions.
diff --git a/docs/concepts/reftypes.dot b/docs/concepts/reftypes.dot
@@ -0,0 +1,88 @@
+digraph  reftypes{
+    rankdir = LR;
+    nodesep=0.5
+    splines=ortho
+	graph [
+		fontname = "Helvetica,Arial,sans-serif"
+        dpi=600
+	]
+	node [
+		style=filled
+		pencolor="#00000044" // frames color
+		fontname="Helvetica,Arial,sans-serif"
+        penwidth=1
+	]
+	edge [
+		arrowsize=0.5
+		labelfontcolor="#00000080"
+		penwidth=2
+	]
+
+
+   {
+        rank=same
+        color="#00000080"
+        artifact [
+            color="#88000022"
+            shape=plain
+            label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                <tr> <td PORT="f0"> <b>Manifest</b> </td> </tr>
+                 <tr> <td>OCI Artifact </td> </tr>
+            </table>>
+        ]
+
+        dot1 [shape=point width=0]
+        dot2 [shape=point width=0]
+        artifact -> dot1 [dir=back]
+        dot1 -> dot2 [arrowhead=none]
+    }
+
+    {
+
+        label="Referrers"
+        signature [
+            fillcolor=lightyellow
+            label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                <tr> <td> <b>Signature</b> </td> </tr>
+                    <tr> <td align="left">... <br align="left"/></td></tr>
+                    <tr> <td align="left" PORT="f0" >subject : <i>descriptor</i><br align="left"/></td></tr>
+            </table>>
+            shape=plain
+        ]
+
+        {
+            rank=same
+            sbom [
+                rank=min
+                fillcolor="#88ff0022"
+                label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                    <tr> <td> <b>SBOM</b> </td> </tr>
+                        <tr> <td align="left">... <br align="left"/></td></tr>
+                        <tr> <td align="left" PORT="f0" >subject : <i>descriptor</i><br align="left"/></td></tr>
+                </table>>
+                shape=plain
+            ]
+            dot21  [shape=point width=0]
+            sbom -> dot21 [dir=back]
+        }
+
+
+
+        sbomsig [
+            newrank=true
+            fillcolor=lightyellow
+            label=<<table border="0" cellborder="1" cellspacing="0" cellpadding="5">
+                <tr> <td> <b>Signature</b> </td> </tr>
+                    <tr> <td align="left">... <br align="left"/></td></tr>
+                    <tr> <td align="left" PORT="f0" >subject : <i>descriptor</i><br align="left"/></td></tr>
+            </table>>
+            shape=plain
+        ]
+
+            dot21 -> sbomsig:f0 [arrowhead=none;  weight=20]
+    }  
+
+    dot1 -> signature:f0 [arrowhead=none; weight=20]
+    dot2 -> sbom:f0 [arrowhead=none;  weight=20]
+
+}
diff --git a/docs/concepts/reftypes.mdx b/docs/concepts/reftypes.mdx
@@ -0,0 +1,190 @@
+---
+title: Attached Artifacts
+sidebar_position: 1
+---
+
+# Attaching and listing reference types
+
+The OCI distribution specification allows us to "link" [OCI artifacts](artifact.mdx) through the use of the concept of reference types.
+Artifacts can be tied to one another by defining one as a subject of another.
+This is crucial for maintaining dependencies between different artifacts and enabling the movement of artifacts and their dependencies between environments.
+
+## Implementing Reference Types in OCI artifacts
+
+The concept of linking or relating OCI artifacts is achieved using the concept of reference types, where one artifact can be set as a subject to another. In this context, "subject" refers to the target of a reference.
+
+### The Art of Associating Artifacts
+
+Consider a typical cloud-native environment with countless OCI artifacts. Often, it's imperative to manage relationships between them—say, an OCI artifact's signatures, or metadata about an artifact. This is where reference types come into the picture.
+
+A reference type enables an OCI artifact to refer to another, creating a defined link or association between them. This association can be for various purposes, such as versioning, updates, signatures, or dependencies.
+
+![OCI artifact with refererrs pointing to the artifact](/img/concepts/reftypes.png)
+
+## Creating a Reference Artifact
+
+OCI Artifacts may be stored in a content-addressable storage system or OCI Layout directory. For the purpose of this guide, we'll use the OCI Distribution Specification to create and list reference types.
+
+The creation of a reference artifact is a two-step process:
+
+1. **Step One**: Put an artifact, say Artifact A, using the PUT Manifest and blob upload APIs if the artifact has blob content.
+    - The prerequisite for a reference type is that the subject artifact must exist in the repository.
+
+2. **Step Two**: Put another artifact, say Artifact B, which refers to Artifact A. In this case, Artifact A is the 'subject' of Artifact B.
+    - This is done using the [push workflow][push-workflow] in the distribution specification.
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Registry
+    C->>R: PUT /v2/<name>/manifests/<tag> Artifact A
+    R-->>C: 201 Created
+    C->>R: PUT /v2/<name>/manifests/<digest> Artifact B with reference to Artifact A
+    R-->>C: 201 Created
+```
+
+In this sequence, the client first uploads Artifact A to the registry. Next, the client uploads Artifact B to the same registry, but this time with a reference to Artifact A by specifying the digest of Artifact A as the subject.
+The association is now established in the registry.
+
+The following example shows the manifest of Artifact B with a reference to Artifact A in the `subject` field.
+
+```json
+ {
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "artifactType" : "application/example",
+  "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": "attach/hello.txt"
+      }
+    }
+  ],
+  "subject": {
+    "mediaType": "application/vnd.oci.image.manifest.v1+json",
+    "digest": "sha256:5e140a61e16155b30356685a6801e5250339bfb11370e70573d28d4ff2dc89cf",
+    "size": 477
+  },
+  "annotations": {
+    "org.opencontainers.image.created": "2023-08-05T06:58:38Z"
+  }
+}
+```
+
+## Listing Referrers
+
+Once an artifact has one or more referring artifacts, it's often necessary to list these referrers for various purposes such as tracking dependencies, updates or obtaining metadata of the artifact.
+The OCI [Distribution Specification][listing-referrers] defines an API endpoint (`/v2/<name>/referrers/<digest>`) for this purpose.
+
+If the registry does not support listing referrers then the [referrers tag schema][tag-schema] may be used to obtain and static list Index of refererres.
+
+For the purpose of this guide we will use the [referrers API][listing-referrers].
+
+### Listing all referrers
+
+In this sequence, the client requests a list of all referrers to a specific artifact from the registry, which then responds with the list.
+The list may be paginated if the number of referrers is large.
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Registry
+    C->>R: GET /v2/<name>/referrers/<digest>
+    R-->>C: 200 OK (List of all referrers)
+```
+
+### Listing referrers with a specific artifact type
+
+In this sequence, the client requests a list of referrers to a specific artifact of a certain media type from the registry, which then responds with the filtered list.
+The response will include the `OCI-Filters-Applied: artifactType` header to indicate that the response is filtered by the `artifactType` query parameter.
+
+The artifact type is determied by the same rules as per [OCI artifacts guidlines](artifact.mdx#determining-the-artifact-type).
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Registry
+    C->>R: GET /v2/<name>/referrers/<digest>?artifactType=<artifactType>
+    R-->>C: 200 OK (List of referrers of specific media type)
+```
+
+The request below lists shows an example for listing referrers of a specific media type.
+
+```json
+GET /v2/hello-world/referrers/sha256:5e140a6..?artifactType=application/example HTTP/1.1
+
+// response
+Content-Type: application/vnd.oci.image.index.v1+json
+Oci-Filters-Applied: artifactType
+
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.index.v1+json",
+  "manifests": [
+    {
+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "digest": "sha256:a10d2cf503458e48996a3e3030c75fb5f5cd967e21a38ca69ce6c1e1dee5fd27",
+      "size": 677,
+      "annotations": {
+        "org.opencontainers.image.created": "2023-08-05T07:08:43Z"
+      },
+      "artifactType": "application/example"
+    }
+  ]
+}
+```
+
+## Fetching the reference artifact
+
+Once the referrers have been queried, the client may fetch the reference artifact using the digest that is returned in the list of referrers.
+The client may then use the digest to fetch the artifact contents using the [pull workflow][pull-workflow] as described in the distribution specification.
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant R as Registry
+
+    Note over C,R: Pull Workflow Starts
+
+    C->>R: GET /v2/<name>/manifests/<tag>
+    R-->>C: 200 OK, return manifest
+
+    Note over C,R: If manifest has config
+
+    C->>R: GET /v2/<name>/blobs/<digest> (Config)
+    R-->>C: 200 OK, return config
+
+    Note over C,R: If manifest has blobs
+
+    C->>R: GET /v2/<name>/blobs/<digest> (Blob 1)
+    R-->>C: 200 OK, return blob 1
+
+    C->>R: GET /v2/<name>/blobs/<digest> (Blob 2)
+    R-->>C: 200 OK, return blob 2
+
+    Note over C,R: Save to OCI Layout or file system
+
+    C->>+C: Save manifest, config and blobs 
+    Note over C: Pull Workflow Ends
+```
+
+## The Power of Associations
+
+The ability to create and list referrers opens a world of possibilities in managing and tracking OCI Artifacts.
+From versioning to updates, and from dependencies to signatures, the use of reference types ensures that we can effectively maintain the complex web of relationships between various OCI Artifacts in a cloud-native environment.
+
+To further explore this concept, dive deeper into the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) and the [OCI Image Specification](https://github.com/opencontainers/image-spec).
+These comprehensive guides will provide more insights into the use of reference types and other details of managing OCI Artifacts.
+
+[listing-referrers]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers
+[pull-workflow]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pull
+[push-workflow]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#push
+[tag-schema]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#referrers-tag-schema
diff --git a/static/img/concepts/reftypes.png b/static/img/concepts/reftypes.png