buildx/docs/guides/cache/s3.md

AWS S3 cache storage

Warning

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

The s3 cache store uploads your resulting build cache to AWS's S3 file storage service, into a bucket of your choice.

Note

The s3 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 docker-container driver (which can act as a simple drop-in replacement):

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

To import and export your cache using the s3 storage backend we use the --cache-to and --cache-from flags and point it to our desired bucket using the required region and bucket parameters:

$ docker buildx build --push -t <user>/<image> \
  --cache-to type=s3,region=eu-west-1,bucket=my_bucket,name=my_image \
  --cache-from type=s3,region=eu-west-1,bucket=my_bucket,name=my_image

Authentication

To authenticate to S3 to read from and write to the cache, the following parameters are required:

• access_key_id: access key ID
• secret_access_key: secret access key
• session_token: session token

While these can be manually provided, if left unspecified, then the credentials for S3 will be pulled from the BuildKit server's environment following the environment variables scheme for the AWS Go SDK.

Warning

These environment variables must be specified on the BuildKit server, not the buildx client.

Cache options

The s3 cache has lots of parameters to adjust its behavior.

Cache mode

See Registry - Cache mode for more information.

Further reading

For an introduction to caching see Optimizing builds with cache management.

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