Merge branch 'oras-project:main' into oras-completion

docs/commands/oras_attach.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras attach
-sidebar_position: 1
+sidebar_position: 10
 ---
 
 # oras attach

docs/commands/oras_blob_delete.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras blob delete
-sidebar_position: 2
+sidebar_position: 20
 ---
 
 # oras blob delete

docs/commands/oras_blob_fetch.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras blob fetch
-sidebar_position: 3
+sidebar_position: 30
 ---
 
 # oras blob fetch

docs/commands/oras_blob_push.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras blob push
-sidebar_position: 4
+sidebar_position: 40
 ---
 
 # oras blob push

docs/commands/oras_copy.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras copy
-sidebar_position: 5
+sidebar_position: 50
 ---
 
 # oras copy

docs/commands/oras_discover.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras discover
-sidebar_position: 6
+sidebar_position: 60
 ---
 
 # oras discover

docs/commands/oras_login.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras login
-sidebar_position: 7
+sidebar_position: 70
 ---
 
 # oras login

docs/commands/oras_logout.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras logout
-sidebar_position: 8
+sidebar_position: 80
 ---
 
 # oras logout

docs/commands/oras_manifest_delete.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras manifest delete
-sidebar_position: 9
+sidebar_position: 90
 ---
 
 # oras manifest delete

docs/commands/oras_manifest_fetch-config.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras manifest fetch-config
-sidebar_position: 10
+sidebar_position: 100
 ---
 
 # oras manifest fetch-config

docs/commands/oras_manifest_fetch.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras manifest fetch
-sidebar_position: 11
+sidebar_position: 110
 ---
 
 # oras manifest fetch

docs/commands/oras_manifest_push.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras manifest push
-sidebar_position: 12
+sidebar_position: 120
 ---
 
 # oras manifest push

docs/commands/oras_pull.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras pull
-sidebar_position: 13
+sidebar_position: 130
 ---
 
 # oras pull

docs/commands/oras_push.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras push
-sidebar_position: 14
+sidebar_position: 140
 ---
 
 # oras push

docs/commands/oras_repo_ls.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras repo ls
-sidebar_position: 15
+sidebar_position: 150
 ---
 
 # oras repo ls

docs/commands/oras_repo_tags.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras repo tags
-sidebar_position: 16
+sidebar_position: 160
 ---
 
 # oras repo tags

docs/commands/oras_tag.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras tag
-sidebar_position: 17
+sidebar_position: 170
 ---
 
 # oras tag

docs/commands/oras_version.mdx

@@ -1,6 +1,6 @@
 ---
 title: oras version
-sidebar_position: 18
+sidebar_position: 180
 ---
 
 # oras version

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