# 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](https://aws.amazon.com/s3/),
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](../drivers/index.md). To create a new docker-container driver (which
> can act as a simple drop-in replacement):
>
> ```console
> 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:

```console
$ 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](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html).

> **Warning**
>
> These environment variables **must** be specified on the BuildKit server, not
> the `buildx` client.

<!-- FIXME: update once https://github.com/docker/buildx/pull/1294 is released -->

## Cache options

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

### Cache mode

See [Registry - Cache mode](./registry.md#cache-mode) for more information.

## Further reading

For an introduction to caching see [Optimizing builds with cache management](https://docs.docker.com/build/building/cache).

For more information on the `s3` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#s3-cache-experimental).