buildx/docs/guides/cache/s3.md

Amazon S3 cache storage

Warning

This cache backend is unreleased. You can use it today, by using the moby/buildkit:master image in your Buildx driver.

The s3 cache storage uploads your resulting build cache to Amazon S3 file storage service, into a specified bucket.

Note

This cache storage backend requires using a different driver than the default docker driver - see more information on selecting a driver here. To create a new driver (which can act as a simple drop-in replacement):

$ docker buildx create --use --driver=docker-container

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

Authentication

access_key_id, secret_access_key, and session_token, if left unspecified, are read from environment variables on the BuildKit server following the scheme for the AWS Go SDK. The environment variables are read from the server, not the Buildx client.

Further reading

For an introduction to caching see Optimizing builds with cache.

For more information on the s3 cache backend, see the BuildKit README.