From 74a822568e5f98d5ab63026e7fcc1a7e01220b01 Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Wed, 28 Sep 2022 14:13:13 +0200 Subject: [PATCH 1/2] added tables for cache parameters Signed-off-by: David Karlsson --- docs/guides/cache/azblob.md | 26 ++++++++++---------- docs/guides/cache/gha.md | 25 +++++++++---------- docs/guides/cache/local.md | 45 ++++++++++++++++------------------- docs/guides/cache/registry.md | 29 +++++++++++----------- docs/guides/cache/s3.md | 28 ++++++++++++---------- 5 files changed, 75 insertions(+), 78 deletions(-) diff --git a/docs/guides/cache/azblob.md b/docs/guides/cache/azblob.md index fd3b10d2..faf5334e 100644 --- a/docs/guides/cache/azblob.md +++ b/docs/guides/cache/azblob.md @@ -27,20 +27,18 @@ $ docker buildx build . --push -t / \ --cache-from type=azblob,name=[,parameters...] ``` -Common parameters: - -- `name`: the name of the cache image. -- `account_url`: the base address of the blob storage account, for example: - `https://myaccount.blob.core.windows.net`. See - [authentication](#authentication). -- `secret_access_key`: specifies the - [Azure Blob Storage account key](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage), - see [authentication](#authentication). - -Parameters for `--cache-to`: - -- `mode`: specify cache layers to export (default: `min`), see - [cache mode](./index.md#cache-mode) +The following table describes the available CSV parameters that you can pass to +`--cache-to` and `--cache-from`. + +| Parameter | Option | Value | Default | Description | +| ------------------- | ---------- | ---------- | ------- | -------------------------------------------------- | +| `name` | Both | String | | Required. The name of the cache image. | +| `account_url` | Both | String | | Base URL of the storage account. | +| `secret_access_key` | Both | String | | Blob storage account key, see [authentication][1]. | +| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][2]. | + +[1]: #authentication +[2]: index.md#cache-mode ## Authentication diff --git a/docs/guides/cache/gha.md b/docs/guides/cache/gha.md index e02e1ccf..ef71307e 100644 --- a/docs/guides/cache/gha.md +++ b/docs/guides/cache/gha.md @@ -31,18 +31,19 @@ $ docker buildx build . --push -t / \ --cache-from type=gha[,parameters...] ``` -Common parameters: - -- `url`: cache server URL (default `$ACTIONS_CACHE_URL`), see - [authentication](#authentication) -- `token`: access token (default `$ACTIONS_RUNTIME_TOKEN`), see - [authentication](#authentication) -- `scope`: cache scope (defaults to the name of the current Git branch). - -Parameters for `--cache-to`: - -- `mode`: specify cache layers to export (default: `min`), see - [cache mode](./index.md#cache-mode) +The following table describes the available CSV parameters that you can pass to +`--cache-to` and `--cache-from`. + +| Parameter | Option | Value | Default | Description | +| --------- | ---------- | ---------- | ------------------------------- | -------------------------------------------- | +| `url` | Both | String | `$ACTIONS_CACHE_URL` | Cache server URL, see [authentication][1]. | +| `token` | Both | String | `$ACTIONS_RUNTIME_TOKEN` | Access token, see [authentication][1]. | +| `scope` | Both | String | Name of the current Git branch. | Cache scope, see [scope][2] | +| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][3]. | + +[1]: #authentication +[2]: #scope +[3]: index.md#cache-mode ## Authentication diff --git a/docs/guides/cache/local.md b/docs/guides/cache/local.md index fc06fec9..c2e9d140 100644 --- a/docs/guides/cache/local.md +++ b/docs/guides/cache/local.md @@ -26,30 +26,27 @@ $ docker buildx build . --push -t / \ --cache-from type=local,src=path/to/local/dir, ``` -Parameters for `--cache-to`: - -- `dest`: absolute or relative path to the local directory where you want to - export the cache to. -- `mode`: specify cache layers to export (default: `min`), see - [cache mode](./index.md#cache-mode) -- `oci-mediatypes`: whether to use OCI media types in exported manifests - (default `true`, since BuildKit `v0.8`), see - [OCI media types](./index.md#oci-media-types) -- `compression`: compression type for layers newly created and cached (default: - `gzip`), see [cache compression](./index.md#cache-compression) -- `compression-level`: compression level for `gzip`, `estargz` (0-9) and `zstd` - (0-22) -- `force-compression`: forcibly apply `compression` option to all layers - -Parameters for `--cache-from`: - -- `src`: absolute or relative path to the local directory where you want to - import cache from. -- `digest`: specify explicit digest of the manifest list to import, see - [cache versioning](#cache-versioning) - - If the `src` cache doesn't exist, then the cache import step will fail, but - the build will continue. +The following table describes the available CSV parameters that you can pass to +`--cache-to` and `--cache-from`. + +| Parameter | Option | Value | Default | Description | +| ------------------- | ------------ | --------------------- | ------- | -------------------------------------------------------------------- | +| `src` | `cache-from` | String | | Path of the local directory where cache gets imported from. | +| `digest` | `cache-from` | String | | Digest of manifest to import, see [cache versioning][4]. | +| `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. | +| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][1]. | +| `oci-mediatypes` | `cache-to` | `true\|false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. | +| `compression` | `cache-to` | `gzip\|estargz\|zstd` | `gzip` | Compression type, see [cache compression][3]. | +| `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. | +| `force-compression` | `cache-to` | `true\|false` | `false` | Forcibly apply compression. | + +[1]: index.md#cache-mode +[2]: index.md#oci-media-types +[3]: index.md#cache-compression +[4]: #cache-versioning + +If the `src` cache doesn't exist, then the cache import step will fail, but the +build will continue. ## Cache versioning diff --git a/docs/guides/cache/registry.md b/docs/guides/cache/registry.md index 830cc7a8..2755ab47 100644 --- a/docs/guides/cache/registry.md +++ b/docs/guides/cache/registry.md @@ -34,23 +34,22 @@ $ docker buildx build . --push -t / \ --cache-from type=registry,ref=/ ``` -Common parameters: +The following table describes the available CSV parameters that you can pass to +`--cache-to` and `--cache-from`. -- `ref`: full address and name of the cache image that you want to import or - export. +| Parameter | Option | Value | Default | Description | +| ------------------- | ---------- | --------------------- | ------- | -------------------------------------------------------------------- | +| `ref` | Both | String | | Full name of the cache image to import. | +| `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. | +| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][1]. | +| `oci-mediatypes` | `cache-to` | `true\|false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. | +| `compression` | `cache-to` | `gzip\|estargz\|zstd` | `gzip` | Compression type, see [cache compression][3]. | +| `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. | +| `force-compression` | `cache-to` | `true\|false` | `false` | Forcibly apply compression. | -Parameters for `--cache-to`: - -- `mode`: specify cache layers to export (default: `min`), see - [cache mode](./index.md#cache-mode) -- `oci-mediatypes`: whether to use OCI media types in exported manifests - (default `true`, since BuildKit `v0.8`), see - [OCI media types](./index.md#oci-media-types) -- `compression`: compression type for layers newly created and cached (default: - `gzip`), see [cache compression](./index.md#cache-compression) -- `compression-level`: compression level for `gzip`, `estargz` (0-9) and `zstd` - (0-22) -- `force-compression`: forcibly apply `compression` option to all layers +[1]: index.md#cache-mode +[2]: index.md#oci-media-types +[3]: index.md#cache-compression You can choose any valid value for `ref`, as long as it's not the same as the target location that you push your image to. You might choose different tags diff --git a/docs/guides/cache/s3.md b/docs/guides/cache/s3.md index 28b217f1..21e6d5b8 100644 --- a/docs/guides/cache/s3.md +++ b/docs/guides/cache/s3.md @@ -28,19 +28,21 @@ $ docker buildx build . --push -t / \ --cache-from type=s3,region=,bucket=,name= ``` -Common parameters: - -- `region`: geographic location -- `bucket`: name of the S3 bucket used for caching -- `name`: name of the cache image -- `access_key_id`: access key ID, see [authentication](#authentication) -- `secret_access_key`: secret access key, see [authentication](#authentication) -- `session_token`: session token, see [authentication](#authentication) - -Parameters for `--cache-to`: - -- `mode`: specify cache layers to export (default: `min`), see - [cache mode](./index.md#cache-mode) +The following table describes the available CSV parameters that you can pass to +`--cache-to` and `--cache-from`. + +| Parameter | Option | Value | Default | Description | +| ------------------- | ---------- | ---------- | ------- | -------------------------------------------- | +| `region` | Both | String | | Geographic location. | +| `bucket` | Both | String | | Name of the S3 bucket used for caching | +| `name` | Both | String | | Name of the cache image | +| `access_key_id` | Both | String | | See [authentication][1] | +| `secret_access_key` | Both | String | | See [authentication][1] | +| `session_token` | Both | String | | See [authentication][1] | +| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][2]. | + +[1]: #authentication +[2]: index.md#cache-mode ## Authentication From 4d6e36df990f4dcc9cdce7196a99a048a20de6c0 Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Tue, 4 Oct 2022 12:58:00 +0200 Subject: [PATCH 2/2] review comments, align style with driver docs Signed-off-by: David Karlsson --- docs/guides/cache/azblob.md | 12 ++++++------ docs/guides/cache/gha.md | 12 ++++++------ docs/guides/cache/index.md | 17 ++++++++--------- docs/guides/cache/local.md | 20 ++++++++++---------- docs/guides/cache/registry.md | 18 +++++++++--------- docs/guides/cache/s3.md | 18 +++++++++--------- 6 files changed, 48 insertions(+), 49 deletions(-) diff --git a/docs/guides/cache/azblob.md b/docs/guides/cache/azblob.md index faf5334e..810e51ce 100644 --- a/docs/guides/cache/azblob.md +++ b/docs/guides/cache/azblob.md @@ -30,12 +30,12 @@ $ docker buildx build . --push -t / \ The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`. -| Parameter | Option | Value | Default | Description | -| ------------------- | ---------- | ---------- | ------- | -------------------------------------------------- | -| `name` | Both | String | | Required. The name of the cache image. | -| `account_url` | Both | String | | Base URL of the storage account. | -| `secret_access_key` | Both | String | | Blob storage account key, see [authentication][1]. | -| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][2]. | +| Name | Option | Type | Default | Description | +| ------------------- | ----------------------- | ----------- | ------- | -------------------------------------------------- | +| `name` | `cache-to`,`cache-from` | String | | Required. The name of the cache image. | +| `account_url` | `cache-to`,`cache-from` | String | | Base URL of the storage account. | +| `secret_access_key` | `cache-to`,`cache-from` | String | | Blob storage account key, see [authentication][1]. | +| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][2]. | [1]: #authentication [2]: index.md#cache-mode diff --git a/docs/guides/cache/gha.md b/docs/guides/cache/gha.md index ef71307e..9d0e7d5e 100644 --- a/docs/guides/cache/gha.md +++ b/docs/guides/cache/gha.md @@ -34,12 +34,12 @@ $ docker buildx build . --push -t / \ The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`. -| Parameter | Option | Value | Default | Description | -| --------- | ---------- | ---------- | ------------------------------- | -------------------------------------------- | -| `url` | Both | String | `$ACTIONS_CACHE_URL` | Cache server URL, see [authentication][1]. | -| `token` | Both | String | `$ACTIONS_RUNTIME_TOKEN` | Access token, see [authentication][1]. | -| `scope` | Both | String | Name of the current Git branch. | Cache scope, see [scope][2] | -| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][3]. | +| Name | Option | Type | Default | Description | +| ------- | ----------------------- | ----------- | ------------------------------- | -------------------------------------------- | +| `url` | `cache-to`,`cache-from` | String | `$ACTIONS_CACHE_URL` | Cache server URL, see [authentication][1]. | +| `token` | `cache-to`,`cache-from` | String | `$ACTIONS_RUNTIME_TOKEN` | Access token, see [authentication][1]. | +| `scope` | `cache-to`,`cache-from` | String | Name of the current Git branch. | Cache scope, see [scope][2] | +| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][3]. | [1]: #authentication [2]: #scope diff --git a/docs/guides/cache/index.md b/docs/guides/cache/index.md index c290da56..884a011c 100644 --- a/docs/guides/cache/index.md +++ b/docs/guides/cache/index.md @@ -20,24 +20,23 @@ important to keep the runtime of image builds as low as possible. Buildx supports the following cache storage backends: -- [Inline cache](./inline.md) that embeds the build cache into the image. +- `inline-cache`: embeds the build cache into the image. The inline cache gets pushed to the same location as the main output result. Note that this only works for the `image` exporter. -- [Registry cache](./registry.md) that embeds the build cache into a separate - image, and pushes to a dedicated location separate from the main output. +- `registry`: embeds the build cache into a separate image, and pushes to a + dedicated location separate from the main output. -- [Local directory cache](./local.md) that writes the build cache to a local - directory on the filesystem. +- `local`: writes the build cache to a local directory on the filesystem. -- [GitHub Actions cache](./gha.md) that uploads the build cache to - [GitHub](https://docs.github.com/en/rest/actions/cache) (beta). +- `gha`: uploads the build cache to + [GitHub Actions cache](https://docs.github.com/en/rest/actions/cache) (beta). -- [Amazon S3 cache](./s3.md) that uploads the build cache to an +- `s3`: uploads the build cache to an [AWS S3 bucket](https://aws.amazon.com/s3/) (unreleased). -- [Azure Blob Storage cache](./azblob.md) that uploads the build cache to +- `azblob`: uploads the build cache to [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) (unreleased). diff --git a/docs/guides/cache/local.md b/docs/guides/cache/local.md index c2e9d140..b53450d8 100644 --- a/docs/guides/cache/local.md +++ b/docs/guides/cache/local.md @@ -29,16 +29,16 @@ $ docker buildx build . --push -t / \ The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`. -| Parameter | Option | Value | Default | Description | -| ------------------- | ------------ | --------------------- | ------- | -------------------------------------------------------------------- | -| `src` | `cache-from` | String | | Path of the local directory where cache gets imported from. | -| `digest` | `cache-from` | String | | Digest of manifest to import, see [cache versioning][4]. | -| `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. | -| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][1]. | -| `oci-mediatypes` | `cache-to` | `true\|false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. | -| `compression` | `cache-to` | `gzip\|estargz\|zstd` | `gzip` | Compression type, see [cache compression][3]. | -| `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. | -| `force-compression` | `cache-to` | `true\|false` | `false` | Forcibly apply compression. | +| Name | Option | Type | Default | Description | +| ------------------- | ------------ | ----------------------- | ------- | -------------------------------------------------------------------- | +| `src` | `cache-from` | String | | Path of the local directory where cache gets imported from. | +| `digest` | `cache-from` | String | | Digest of manifest to import, see [cache versioning][4]. | +| `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. | +| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][1]. | +| `oci-mediatypes` | `cache-to` | `true`,`false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. | +| `compression` | `cache-to` | `gzip`,`estargz`,`zstd` | `gzip` | Compression type, see [cache compression][3]. | +| `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. | +| `force-compression` | `cache-to` | `true`,`false` | `false` | Forcibly apply compression, see [cache compression][3]. | [1]: index.md#cache-mode [2]: index.md#oci-media-types diff --git a/docs/guides/cache/registry.md b/docs/guides/cache/registry.md index 2755ab47..aa7ab152 100644 --- a/docs/guides/cache/registry.md +++ b/docs/guides/cache/registry.md @@ -37,15 +37,15 @@ $ docker buildx build . --push -t / \ The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`. -| Parameter | Option | Value | Default | Description | -| ------------------- | ---------- | --------------------- | ------- | -------------------------------------------------------------------- | -| `ref` | Both | String | | Full name of the cache image to import. | -| `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. | -| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][1]. | -| `oci-mediatypes` | `cache-to` | `true\|false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. | -| `compression` | `cache-to` | `gzip\|estargz\|zstd` | `gzip` | Compression type, see [cache compression][3]. | -| `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. | -| `force-compression` | `cache-to` | `true\|false` | `false` | Forcibly apply compression. | +| Name | Option | Type | Default | Description | +| ------------------- | ----------------------- | ----------------------- | ------- | -------------------------------------------------------------------- | +| `ref` | `cache-to`,`cache-from` | String | | Full name of the cache image to import. | +| `dest` | `cache-to` | String | | Path of the local directory where cache gets exported to. | +| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][1]. | +| `oci-mediatypes` | `cache-to` | `true`,`false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. | +| `compression` | `cache-to` | `gzip`,`estargz`,`zstd` | `gzip` | Compression type, see [cache compression][3]. | +| `compression-level` | `cache-to` | `0..22` | | Compression level, see [cache compression][3]. | +| `force-compression` | `cache-to` | `true`,`false` | `false` | Forcibly apply compression, see [cache compression][3]. | [1]: index.md#cache-mode [2]: index.md#oci-media-types diff --git a/docs/guides/cache/s3.md b/docs/guides/cache/s3.md index 21e6d5b8..15c7002d 100644 --- a/docs/guides/cache/s3.md +++ b/docs/guides/cache/s3.md @@ -31,15 +31,15 @@ $ docker buildx build . --push -t / \ The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`. -| Parameter | Option | Value | Default | Description | -| ------------------- | ---------- | ---------- | ------- | -------------------------------------------- | -| `region` | Both | String | | Geographic location. | -| `bucket` | Both | String | | Name of the S3 bucket used for caching | -| `name` | Both | String | | Name of the cache image | -| `access_key_id` | Both | String | | See [authentication][1] | -| `secret_access_key` | Both | String | | See [authentication][1] | -| `session_token` | Both | String | | See [authentication][1] | -| `mode` | `cache-to` | `min\|max` | `min` | Cache layers to export, see [cache mode][2]. | +| Name | Option | Type | Default | Description | +| ------------------- | ----------------------- | ----------- | ------- | -------------------------------------------- | +| `region` | `cache-to`,`cache-from` | String | | Geographic location. | +| `bucket` | `cache-to`,`cache-from` | String | | Name of the S3 bucket used for caching | +| `name` | `cache-to`,`cache-from` | String | | Name of the cache image | +| `access_key_id` | `cache-to`,`cache-from` | String | | See [authentication][1] | +| `secret_access_key` | `cache-to`,`cache-from` | String | | See [authentication][1] | +| `session_token` | `cache-to`,`cache-from` | String | | See [authentication][1] | +| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][2]. | [1]: #authentication [2]: index.md#cache-mode