diff --git a/docs/guides/cache/azblob.md b/docs/guides/cache/azblob.md index fd3b10d2..810e51ce 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`. + +| 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 ## Authentication diff --git a/docs/guides/cache/gha.md b/docs/guides/cache/gha.md index e02e1ccf..9d0e7d5e 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`. + +| 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 +[3]: index.md#cache-mode ## Authentication 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 fc06fec9..b53450d8 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`. + +| 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 +[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..aa7ab152 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. +| 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]. | -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..15c7002d 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`. + +| 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 ## Authentication