From d9c1469b73f8cc1742693ee19dda1619415f6d4e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 9 Dec 2024 12:57:51 +0100 Subject: [PATCH 1/6] build: add oci-artifact exporter opt Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .../manuals/build/exporters/image-registry.md | 2 + .../build/metadata/attestations/_index.md | 81 +++++++++++++++++++ 2 files changed, 83 insertions(+) diff --git a/content/manuals/build/exporters/image-registry.md b/content/manuals/build/exporters/image-registry.md index f807c2980a4f..159be14265fa 100644 --- a/content/manuals/build/exporters/image-registry.md +++ b/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.` | 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 diff --git a/content/manuals/build/metadata/attestations/_index.md b/content/manuals/build/metadata/attestations/_index.md index fc9530a05b5e..e18977bf4679 100644 --- a/content/manuals/build/metadata/attestations/_index.md +++ b/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: From 1a9dc69bd0c2f425673ad3ca088b5b8cd947f004 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 17 Jan 2025 17:06:00 +0100 Subject: [PATCH 2/6] chore: tidy templates, add comments Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- layouts/_default/search.html | 8 ++++++++ layouts/index.metadata.json | 2 +- layouts/index.redirects.json | 22 ++++++++++++++++++++++ layouts/index.robots.txt | 6 ++++++ layouts/partials/github-links.html | 5 +++++ layouts/partials/head.html | 11 ----------- layouts/partials/meta.html | 9 ++++----- layouts/partials/pagemeta.html | 7 +++++++ layouts/partials/search-bar.html | 8 ++++++++ layouts/partials/sidebar/guides.html | 8 ++++++++ layouts/partials/sidebar/mainnav.html | 6 ++++++ layouts/partials/sidebar/sections.html | 8 ++++++++ layouts/partials/sidebar/tags.html | 5 +++++ layouts/partials/tooltip.html | 4 ++++ layouts/partials/utils/css.html | 5 +++++ layouts/partials/utils/description.html | 6 ++++++ layouts/partials/utils/keywords.html | 6 ++++++ layouts/partials/utils/title.html | 17 ----------------- layouts/sitemap.xml | 5 +++++ tailwind.config.js | 6 ------ 20 files changed, 114 insertions(+), 40 deletions(-) delete mode 100644 layouts/partials/utils/title.html diff --git a/layouts/_default/search.html b/layouts/_default/search.html index 1f9a03e168ab..f4e70cfe061f 100644 --- a/layouts/_default/search.html +++ b/layouts/_default/search.html @@ -35,6 +35,14 @@

{{ .Title }}

window.addEventListener("load", async function () { // Hydrate pagefind pagefind = await import("/pagefind/pagefind.js"); + await pagefind.options({ + ranking: { + termFrequency: 0.2, + pageLength: 0.75, + termSaturation: 1.4, + termSimilarity: 6.0, + }, + }); // Get the query parameter from the URL const urlParams = new URLSearchParams(window.location.search); diff --git a/layouts/index.metadata.json b/layouts/index.metadata.json index e3426bb18d26..acfaf21f2b80 100644 --- a/layouts/index.metadata.json +++ b/layouts/index.metadata.json @@ -1,6 +1,6 @@ [ {{- range where site.Pages "Params.sitemap" "!=" false -}} - {{- $title := partialCached "utils/title.html" . . -}} + {{- $title := .LinkTitle -}} {{- $desc := partialCached "utils/description.html" . . -}} {{- $kwd := partialCached "utils/keywords.html" . . -}} {{- $tags := slice -}} diff --git a/layouts/index.redirects.json b/layouts/index.redirects.json index 5add5074019b..6229dfc8d185 100644 --- a/layouts/index.redirects.json +++ b/layouts/index.redirects.json @@ -1,3 +1,25 @@ +{{- /* + + This template generates the redirects.json file used to generate 301 + redirects in production. It takes all the redirects defined in + data/redirects.yml, as well as all the aliases defined in front matter, and + outputs a simple key-value JSON file: + + { + "": "", + ... + } + + e.g. + + { + "/engine/reference/builder/": "/reference/dockerfile/", + ... + } + + */ +-}} + {{- $redirects := newScratch }} {{- range $i, $e := site.AllPages -}} {{- if .Params.aliases -}} diff --git a/layouts/index.robots.txt b/layouts/index.robots.txt index d3590928c9e8..3e9a658fdf96 100644 --- a/layouts/index.robots.txt +++ b/layouts/index.robots.txt @@ -1,3 +1,9 @@ +{{- /* + For Netlify deployments, we disallow all routes to prevent search + engines from indexing our preview sites. + */ +-}} + {{- if hugo.IsProduction -}} User-agent: * diff --git a/layouts/partials/github-links.html b/layouts/partials/github-links.html index 75ce8d543290..1f7e518b7393 100644 --- a/layouts/partials/github-links.html +++ b/layouts/partials/github-links.html @@ -1,3 +1,8 @@ +{{- /* + Adds links for editing the page or requesting changes: + - "Edit this page": Only in production, skips files from `_vendor/` (upstream repositories). + - "Request changes": Links to a pre-filled issue form. +*/ -}} {{ if hugo.IsProduction }} {{ with .File }} {{ if not (in .Filename "/_vendor/") }} diff --git a/layouts/partials/head.html b/layouts/partials/head.html index cadc04249b8e..0edada5a576b 100644 --- a/layouts/partials/head.html +++ b/layouts/partials/head.html @@ -1,16 +1,5 @@ - {{ partial "meta.html" . }} {{- if hugo.IsProduction -}} + diff --git a/layouts/partials/pagemeta.html b/layouts/partials/pagemeta.html index f799522409eb..426897e23e74 100644 --- a/layouts/partials/pagemeta.html +++ b/layouts/partials/pagemeta.html @@ -1,3 +1,10 @@ +{{- /* + Renders a table of contents (ToC) for the page. + - Uses `.Fragments.Headings` to generate a nested ToC if headings exist and `notoc` is not set to `true`. + - Limits heading levels to a min and max range (`$min` and `$max`). + - Wraps the ToC in a `data-pagefind-ignore` container to exclude it from search indexing. + - Includes a recursive template (`walkHeadingFragments`) to handle nested headings. +*/ -}} {{- $toc := false }} {{- with .Fragments }} {{- $toc = and (ne page.Params.notoc true) .Headings }} diff --git a/layouts/partials/search-bar.html b/layouts/partials/search-bar.html index 72da1f4e5c0e..6595e32d3ff7 100644 --- a/layouts/partials/search-bar.html +++ b/layouts/partials/search-bar.html @@ -43,6 +43,14 @@