Amazon S3 cache

Table of contents

Restricted

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 service or other S3-compatible services, such as MinIO.

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.
`upload_parallelism`	`cache-to`	Integer	`4`	Number of parallel layer uploads.
`touch_refresh`	`cache-to`	Time	`24h`	Interval for updating the timestamp of unchanged cache layers.
`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.

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 Credentials for details about authentication using environment variables and credentials file.

Amazon S3 cache

Synopsis

Authentication

Further reading