From 74a822568e5f98d5ab63026e7fcc1a7e01220b01 Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Wed, 28 Sep 2022 14:13:13 +0200 Subject: [PATCH] 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