Merge pull request #21588 from dvdksn/build-oci-artifact-opt

build: add oci-artifact exporter opt

Author: dvdksn

content/manuals/build/exporters/image-registry.md

@@ -37,6 +37,7 @@ The following table describes the available parameters that you can pass to
 | `force-compression`    | `true`,`false`                         | `false` | Forcefully apply compression, see [compression][1]                                                                                                                                                                                  |
 | `rewrite-timestamp`    | `true`,`false`                         | `false` | Rewrite the file timestamps to the `SOURCE_DATE_EPOCH` value. See [build reproducibility][4] for how to specify the `SOURCE_DATE_EPOCH` value.                                                                                      |
 | `oci-mediatypes`       | `true`,`false`                         | `false` | Use OCI media types in exporter manifests, see [OCI Media types][2]                                                                                                                                                                 |
+| `oci-artifact`         | `true`,`false`                         | `false` | Attestations are formatted as OCI artifacts, see [OCI Media types][2]                                                                                                                                                               |
 | `unpack`               | `true`,`false`                         | `false` | Unpack image after creation (for use with containerd)                                                                                                                                                                               |
 | `store`                | `true`,`false`                         | `true`  | Store the result images to the worker's (for example, containerd) image store, and ensures that the image has all blobs in the content store. Ignored if the worker doesn't have image store (when using OCI workers, for example). |
 | `annotation.<key>`     | String                                 |         | Attach an annotation with the respective `key` and `value` to the built image,see [annotations][3]                                                                                                                                  |
@@ -45,6 +46,7 @@ The following table describes the available parameters that you can pass to
 [2]: _index.md#oci-media-types
 [3]: #annotations
 [4]: https://github.com/moby/buildkit/blob/master/docs/build-repro.md
+[5]: /manuals/build/metadata/attestations/_index.md#attestations-as-oci-artifacts
 
 ## Annotations
 

content/manuals/build/metadata/attestations/_index.md

@@ -95,6 +95,8 @@ the attestations to an image manifest, since it's outputting a directory of
 files or a tarball, not an image. Instead, these exporters write the
 attestations to one or more JSON files in the root directory of the export.
 
+## Example
+
 The following example shows a truncated in-toto JSON representation of an SBOM
 attestation.
 
@@ -161,6 +163,85 @@ attestation.
 To deep-dive into the specifics about how attestations are stored, see
 [Image Attestation Storage (BuildKit)](attestation-storage.md).
 
+## Attestation manifest format
+
+Attestations are stored as manifests, referenced by the image's index. Each
+_attestation manifest_ refers to a single _image manifest_ (one
+platform-variant of the image). Attestation manifests contain a single layer,
+the "value" of the attestation.
+
+The following example shows the structure of an attestation manifest:
+
+```json
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "config": {
+    "mediaType": "application/vnd.oci.image.config.v1+json",
+    "size": 167,
+    "digest": "sha256:916d7437a36dd0e258e64d9c5a373ca5c9618eeb1555e79bd82066e593f9afae"
+  },
+  "layers": [
+    {
+      "mediaType": "application/vnd.in-toto+json",
+      "size": 1833349,
+      "digest": "sha256:3138024b98ed5aa8e3008285a458cd25a987202f2500ce1a9d07d8e1420f5491",
+      "annotations": {
+        "in-toto.io/predicate-type": "https://spdx.dev/Document"
+      }
+    }
+  ]
+}
+```
+
+### Attestations as OCI artifacts
+
+You can configure the format of the attestation manifest using the
+[`oci-artifact` option](/manuals/build/exporters/image-registry.md#synopsis)
+for the `image` and `registry` exporters. If set to `true`, the structure of
+the attestation manifest changes as follows:
+
+- An `artifactType` field is added to the attestation manifest, with a value of `application/vnd.docker.attestation.manifest.v1+json`.
+- The `config` field is an [empty descriptor] instead of a "dummy" config.
+- A `subject` field is also added, pointing to the image manifest that the attestation refers to.
+
+[empty descriptor]: https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidance-for-an-empty-descriptor
+
+The following example shows an attestation with the OCI artifact format:
+
+```json
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "artifactType": "application/vnd.docker.attestation.manifest.v1+json",
+  "config": {
+    "mediaType": "application/vnd.oci.empty.v1+json",
+    "size": 2,
+    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+    "data": "e30="
+  },
+  "layers": [
+    {
+      "mediaType": "application/vnd.in-toto+json",
+      "size": 2208,
+      "digest": "sha256:6d2f2c714a6bee3cf9e4d3cb9a966b629efea2dd8556ed81f19bd597b3325286",
+      "annotations": {
+        "in-toto.io/predicate-type": "https://slsa.dev/provenance/v0.2"
+      }
+    }
+  ],
+  "subject": {
+    "mediaType": "application/vnd.oci.image.manifest.v1+json",
+    "size": 1054,
+    "digest": "sha256:bc2046336420a2852ecf915786c20f73c4c1b50d7803aae1fd30c971a7d1cead",
+    "platform": {
+      "architecture": "amd64",
+      "os": "linux"
+    }
+  }
+}
+```
+
 ## What's next
 
 Learn more about the available attestation types and how to use them: