docker
/
buildx
mirror of https://github.com/docker/buildx.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1332 from dvdksn/refactor-cache-docs 

added tables for cache parameters
This commit is contained in:
Justin Chadwell 2022-10-11 12:19:35 +01:00 committed by GitHub
parent 9ad39a29f7 4d6e36df99
commit 361c093a35
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 74 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/guides/cache/azblob.md vendored
View File

@ -27,20 +27,18 @@ $ docker buildx build . --push -t <registry>/<image> \
--cache-from type=azblob,name=<cache-image>[,parameters...]
```
Common parameters:
The following table describes the available CSV parameters that you can pass to
`--cache-to` and `--cache-from`.
- `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).
| 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]. |
Parameters for `--cache-to`:
- `mode`: specify cache layers to export (default: `min`), see
[cache mode](./index.md#cache-mode)
[1]: #authentication
[2]: index.md#cache-mode
## Authentication

21
docs/guides/cache/gha.md vendored
View File

@ -31,18 +31,19 @@ $ docker buildx build . --push -t <registry>/<image> \
--cache-from type=gha[,parameters...]
```
Common parameters:
The following table describes the available CSV parameters that you can pass to
`--cache-to` and `--cache-from`.
- `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).
| 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]. |
Parameters for `--cache-to`:
- `mode`: specify cache layers to export (default: `min`), see
[cache mode](./index.md#cache-mode)
[1]: #authentication
[2]: #scope
[3]: index.md#cache-mode
## Authentication

17
docs/guides/cache/index.md vendored
View File

@ -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).

39
docs/guides/cache/local.md vendored
View File

@ -26,30 +26,27 @@ $ docker buildx build . --push -t <registry>/<image> \
--cache-from type=local,src=path/to/local/dir,
```
Parameters for `--cache-to`:
The following table describes the available CSV parameters that you can pass to
`--cache-to` and `--cache-from`.
- `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
| 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]. |
Parameters for `--cache-from`:
[1]: index.md#cache-mode
[2]: index.md#oci-media-types
[3]: index.md#cache-compression
[4]: #cache-versioning
- `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.
If the `src` cache doesn't exist, then the cache import step will fail, but the
build will continue.
## Cache versioning

29
docs/guides/cache/registry.md vendored
View File

@ -34,23 +34,22 @@ $ docker buildx build . --push -t <registry>/<image> \
--cache-from type=registry,ref=<registry>/<cache-image>
```
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

24
docs/guides/cache/s3.md vendored
View File

@ -28,19 +28,21 @@ $ docker buildx build . --push -t <user>/<image> \
--cache-from type=s3,region=<region>,bucket=<bucket>,name=<cache-image>
```
Common parameters:
The following table describes the available CSV parameters that you can pass to
`--cache-to` and `--cache-from`.
- `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)
| 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]. |
Parameters for `--cache-to`:
- `mode`: specify cache layers to export (default: `min`), see
[cache mode](./index.md#cache-mode)
[1]: #authentication
[2]: index.md#cache-mode
## Authentication