-
Notifications
You must be signed in to change notification settings - Fork 64
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Sajay Antony <[email protected]>
- Loading branch information
1 parent
f96b94c
commit c3e961b
Showing
7 changed files
with
9,007 additions
and
18,354 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| { | ||
| "label": "Concepts", | ||
| "position": 50, | ||
| "link": { | ||
| "type": "generated-index", | ||
| "description": "Concepts" | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,243 @@ | ||
| --- | ||
| 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 and 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. | ||
|
|
||
| ## Exploring OCI artifacts | ||
|
|
||
| An OCI artifact can be accessed from a | ||
| [content addressable storage][cas]like a registry, or an on-disk storage like | ||
| an [OCI-Layout][oci-layout] directory. | ||
|
|
||
| ## 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. The OCI artifact can be access 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. | ||
|
|
||
|  | ||
|
|
||
| ### The Significance of Annotations | ||
|
|
||
| Annotations in OCI artifacts offer a means of adding metadata to various | ||
| components, including the Image Manifest and Image Layers. | ||
| These annotations hold key-value pairs that represent either the metadata | ||
| of the OCI artifact, 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]. | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| B{Is\nmanifest.artifactType\ndefined?} | ||
| B -->|Yes| C[type=manifest.artifactType] | ||
| B -->|No| E[type=manifest.config.mediaType] | ||
| ``` | ||
|
|
||
| ## Dissecting the Manifest | ||
|
|
||
| The structure of the artifact depends on the prupose 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` when artifacts that 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, | ||
| "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" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### 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. An example use case if is when you want to represent | ||
| multiple SBOMs of different architectures under one unified artifact. | ||
|
|
||
| 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. It helps to | ||
| group related artifacts together, providing a single entry-point for accessing any specific | ||
| artifact depending on the required architecture. | ||
|
|
||
| Below is an example of an OCI Image Index for an artifact that represents multiple SBOMs | ||
| of different architectures: | ||
|
|
||
| ```json | ||
| { | ||
| "schemaVersion": 2, | ||
| "artifactType": "application/vnd.example.sbom.v1", | ||
| "manifests": [ | ||
| { | ||
| "mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
| "artifactType": "application/vnd.example.sbom.v1", | ||
| "size": 7143, | ||
| "digest": "sha256:1111...", | ||
| "platform": { | ||
| "architecture": "amd64", | ||
| "os": "linux" | ||
| }, | ||
| }, | ||
| { | ||
| "mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
| "artifactType": "application/vnd.example.sbom.v1", | ||
| "size": 7682, | ||
| "digest": "sha256:2222...", | ||
| "platform": { | ||
| "architecture": "arm64", | ||
| "os": "linux" | ||
| }, | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ## Best Practices and Limitations | ||
|
|
||
| While working with OCI artifacts, keep in mind that not all registries have implemented | ||
| image-spec v1.1. For backward compatibility, OCI artifacts can use the `config.mediaType` | ||
| to represent the artifact type, aligning with the IANA mediaType of the artifact. | ||
|
|
||
| In cases where the creation of an artifact doesn't involve a config blob, make sure to use | ||
| the `artifactType` field in the manifest. If a config blob is indispensable, comply with | ||
| the image specification and employ an empty one. 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 layers and blobs optional—bringing more flexibility to the table. | ||
|
|
||
| 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/main/image-layout.md | ||
| [descriptor]: https://github.com/opencontainers/image-spec/blob/main/descriptor.md | ||
| [image-manifest]: https://github.com/opencontainers/image-spec/blob/main/manifest.md#image-manifest | ||
| [image-properties]: https://github.com/opencontainers/image-spec/blob/main/manifest.md#image-manifest-property-descriptions | ||
| [empty-descriptor]: https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidance-for-an-empty-descriptor | ||
| [image-index]: https://github.com/opencontainers/image-spec/blob/main/image-index.md#image-index-property-descriptions |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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]</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 | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.