Amazon S3 cache
Experimental
This is an experimental feature. The interface and behavior are unstable and may change in future releases.
The s3 cache storage uploads your resulting build cache to
Amazon S3 file storage serviceopen_in_new,
into a specified bucket.
This cache storage backend is not supported with the default docker driver.
To use this feature, create a new builder using a different driver. See
Build drivers for more information.
Synopsis
$ docker buildx build --push -t <user>/<image> \
--cache-to type=s3,region=<region>,bucket=<bucket>,name=<cache-image>[,parameters...] \
--cache-from type=s3,region=<region>,bucket=<bucket>,name=<cache-image> .
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 | Required. Geographic location. | |
bucket | cache-to,cache-from | String | Required. Name of the S3 bucket. | |
name | cache-to,cache-from | String | Name of the cache image. | |
endpoint_url | cache-to,cache-from | String | Endpoint of the S3 bucket. | |
blobs_prefix | cache-to,cache-from | String | Prefix to prepend to blob filenames. | |
manifests_prefix | cache-to,cache-from | String | Prefix to prepend on manifest filenames. | |
use_path_style | cache-to,cache-from | Boolean | false | When true, uses bucket in the URL instead of hostname. |
access_key_id | cache-to,cache-from | String | See authentication. | |
secret_access_key | cache-to,cache-from | String | See authentication. | |
session_token | cache-to,cache-from | String | See authentication. | |
mode | cache-to | min,max | min | Cache layers to export, see cache mode. |
ignore-error | cache-to | Boolean | false | Ignore errors caused by failed cache exports. |
Authentication
Buildx can reuse existing AWS credentials, configured either using a
credentials file or environment variables, for pushing and pulling cache to S3.
Alternatively, you can use the access_key_id, secret_access_key, and
session_token attributes to specify credentials directly on the CLI.
Refer to AWS Go SDK, Specifying Credentialsopen_in_new for details about authentication using environment variables and credentials file.
Further reading
For an introduction to caching see Optimizing builds with cache.
For more information on the s3 cache backend, see the
BuildKit READMEopen_in_new.