From 4903f462f616e453f84d01e6f7c29b23511015b1 Mon Sep 17 00:00:00 2001 From: Justin Chadwell Date: Tue, 17 Jan 2023 11:34:58 +0000 Subject: [PATCH] docs: add reference for new attest family of flags Signed-off-by: Justin Chadwell --- docs/reference/buildx_bake.md | 12 ++++++++-- docs/reference/buildx_build.md | 40 +++++++++++++++++++++++++++++++--- 2 files changed, 47 insertions(+), 5 deletions(-) diff --git a/docs/reference/buildx_bake.md b/docs/reference/buildx_bake.md index c8f9588b..9e94ca3b 100644 --- a/docs/reference/buildx_bake.md +++ b/docs/reference/buildx_bake.md @@ -22,10 +22,10 @@ Build from a file | [`--no-cache`](#no-cache) | | | Do not use cache when building the image | | [`--print`](#print) | | | Print the options without building | | [`--progress`](#progress) | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output | -| `--provenance` | `string` | | Shorthand for `--set=*.attest=type=provenance` | +| [`--provenance`](#provenance) | `string` | | Shorthand for `--set=*.attest=type=provenance` | | [`--pull`](#pull) | | | Always attempt to pull all referenced images | | `--push` | | | Shorthand for `--set=*.output=type=registry` | -| `--sbom` | `string` | | Shorthand for `--set=*.attest=type=sbom` | +| [`--sbom`](#sbom) | `string` | | Shorthand for `--set=*.attest=type=sbom` | | [`--set`](#set) | `stringArray` | | Override target value (e.g., `targetpattern.key=value`) | @@ -125,10 +125,18 @@ $ docker buildx bake -f docker-bake.hcl --print db Same as [`build --progress`](buildx_build.md#progress). +### Create provenance attestations (--provenance) + +Same as [`build --provenance`](buildx_build.md#provenance). + ### Always attempt to pull a newer version of the image (--pull) Same as `build --pull`. +### Create SBOM attestations (--sbom) + +Same as [`build --sbom`](buildx_build.md#sbom). + ### Override target configurations from command line (--set) ``` diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index c510c1c5..f56ab1f6 100644 --- a/docs/reference/buildx_build.md +++ b/docs/reference/buildx_build.md @@ -17,7 +17,7 @@ Start a build |:-------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|:----------|:----------------------------------------------------------------------------------------------------| | [`--add-host`](https://docs.docker.com/engine/reference/commandline/build/#add-host) | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) | | [`--allow`](#allow) | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) | -| `--attest` | `stringArray` | | Attestation parameters (format: `type=sbom,generator=image`) | +| [`--attest`](#attest) | `stringArray` | | Attestation parameters (format: `type=sbom,generator=image`) | | [`--build-arg`](#build-arg) | `stringArray` | | Set build-time variables | | [`--build-context`](#build-context) | `stringArray` | | Additional build contexts (e.g., name=path) | | [`--builder`](#builder) | `string` | | Override the configured builder instance | @@ -37,11 +37,11 @@ Start a build | [`--platform`](#platform) | `stringArray` | | Set target platform for build | | `--print` | `string` | | Print result of information request (e.g., outline, targets) [experimental] | | [`--progress`](#progress) | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output | -| `--provenance` | `string` | | Shortand for `--attest=type=provenance` | +| [`--provenance`](#provenance) | `string` | | Shortand for `--attest=type=provenance` | | `--pull` | | | Always attempt to pull all referenced images | | [`--push`](#push) | | | Shorthand for `--output=type=registry` | | `-q`, `--quiet` | | | Suppress the build output and print image ID on success | -| `--sbom` | `string` | | Shorthand for `--attest=type=sbom` | +| [`--sbom`](#sbom) | `string` | | Shorthand for `--attest=type=sbom` | | [`--secret`](#secret) | `stringArray` | | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`) | | [`--shm-size`](#shm-size) | `bytes` | `0` | Size of `/dev/shm` | | [`--ssh`](#ssh) | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | @@ -66,6 +66,30 @@ here we'll document a subset of the new flags. ## Examples +### Create attestations (--attest) + +``` +--attest=type=sbom,... +--attest=type=provenance,... +``` + +Create [image attestations](https://docs.docker.com/build/attestations/). +BuildKit currently supports: + +- `sbom` - Software Bill of Materials. + + Use `--attest=type=sbom` to generate an SBOM for an image at build-time. + Alternatively, you can use the [`--sbom` shorthand](#sbom). + + For more information, see [here](https://docs.docker.com/build/attestations/sbom/). + +- `provenance` - SLSA Provenance + + Use `--attest=type=provenance` to generate provenance for an image at + build-time. Alternatively, you can use the [`--provenance` shorthand](#provenance). + + For more information, see [here](https://docs.docker.com/build/attestations/slsa-provenance/). + ### Allow extra privileged entitlement (--allow) ``` @@ -451,11 +475,21 @@ $ docker buildx build --load --progress=plain . > Check also our [Color output controls guide](https://github.com/docker/buildx/blob/master/docs/guides/color-output.md) > for modifying the colors that are used to output information to the terminal. +### Create provenance attestations (--provenance) + +Shorthand for [`--attest=type=provenance`](#attest). Enables provenance +attestations for the build result. + ### Push the build result to a registry (--push) Shorthand for [`--output=type=registry`](#registry). Will automatically push the build result to registry. +### Create SBOM attestations (--sbom) + +Shorthand for [`--attest=type=sbom`](#attest). Enables SBOM attestations for +the build result. + ### Secret to expose to the build (--secret) ```