diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx index ed98df7d..c9c29038 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 } ``` -### Arifact authoring decision tree +### Artifact 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 diff --git a/docs/concepts/reftypes.dot b/docs/concepts/reftypes.dot new file mode 100644 index 00000000..e208d973 --- /dev/null +++ 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=< + + +
Manifest
OCI Artifact
> + ] + + dot1 [shape=point width=0] + dot2 [shape=point width=0] + artifact -> dot1 [dir=back] + dot1 -> dot2 [arrowhead=none] + } + + { + + label="Referrers" + signature [ + fillcolor=lightyellow + label=< + + + +
Signature
...
subject : descriptor
> + shape=plain + ] + + { + rank=same + sbom [ + rank=min + fillcolor="#88ff0022" + label=< + + + +
SBOM
...
subject : descriptor
> + shape=plain + ] + dot21 [shape=point width=0] + sbom -> dot21 [dir=back] + } + + + + sbomsig [ + newrank=true + fillcolor=lightyellow + label=< + + + +
Signature
...
subject : descriptor
> + shape=plain + ] + + dot21 -> sbomsig:f0 [arrowhead=none; weight=20] + } + + dot1 -> signature:f0 [arrowhead=none; weight=20] + dot2 -> sbom:f0 [arrowhead=none; weight=20] + +} \ No newline at end of file diff --git a/docs/concepts/reftypes.mdx b/docs/concepts/reftypes.mdx new file mode 100644 index 00000000..426966f0 --- /dev/null +++ b/docs/concepts/reftypes.mdx @@ -0,0 +1,230 @@ +--- +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, supply chain artifacts (signatures, SBOM, etc.), and 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: + +- **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 be known so that it may be added to the subject. + +- **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//manifests/ Artifact A + R-->>C: 201 Created + C->>R: PUT /v2//manifests/ 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. + +:::tip NOTE +The specification does allow pushing the reference artifact **without** requiring +the presense of the the `subject` in the target registry or OCI-Layout. +::: + +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//referrers/`) for this purpose. + +If the registry does not support listing referrers, then the [referrers tag schema][tag-schema] +may be used to obtain a client created non-dynamic 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//referrers/ + 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//referrers/?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%2Fexample 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//manifests/ + R-->>C: 200 OK, return manifest + + Note over C,R: If manifest has config + + C->>R: GET /v2//blobs/ (Config) + R-->>C: 200 OK, return config + + Note over C,R: If manifest has blobs + + C->>R: GET /v2//blobs/ (Blob 1) + R-->>C: 200 OK/307 Redirect, return blob 1 + + C->>R: GET /v2//blobs/ (Blob 2) + R-->>C: 200 OK/307 Redirect 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 introduction of Reference Types (Associations) opens a world of possibilities in +managing and linking of OCI Artifacts while also empowering the following scenarios: + +- Discovery and distribution of artifacts like SBOMs or signatures for supply chain. +- Movement of a graph of OCI content across environments. +- Content management of a graph of artifacts by archiving, deleting or moving them +together. + +To further explore this concept, dive deeper into the +[OCI Distribution Specification][distribution-spec] and the [OCI Image Specification][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/v1.1.0-rc3/spec.md#listing-referrers +[pull-workflow]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#pull +[push-workflow]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#push +[tag-schema]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#referrers-tag-schema +[distribution-spec]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md +[image-spec]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc4/spec.md \ No newline at end of file diff --git a/static/img/concepts/reftypes.png b/static/img/concepts/reftypes.png new file mode 100644 index 00000000..3a2b7854 Binary files /dev/null and b/static/img/concepts/reftypes.png differ