mirror of https://github.com/docker/docs.git
70 lines
3.7 KiB
Markdown
70 lines
3.7 KiB
Markdown
---
|
|
title: Amazon S3 cache
|
|
description: Manage build cache with Amazon S3 buckets
|
|
keywords: build, buildx, cache, backend, s3, buckets, aws
|
|
aliases:
|
|
- /build/building/cache/backends/s3/
|
|
---
|
|
|
|
> **Experimental**
|
|
>
|
|
> This is an experimental feature. The interface and behavior are unstable and
|
|
> may change in future releases.
|
|
{ .restricted }
|
|
|
|
The `s3` cache storage uploads your resulting build cache to
|
|
[Amazon S3 file storage service](https://aws.amazon.com/s3/)
|
|
or other S3-compatible services, such as [MinIO](https://min.io/).
|
|
|
|
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](../../drivers/_index.md) for more information.
|
|
|
|
## Synopsis
|
|
|
|
```console
|
|
$ 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][1]. |
|
|
| `secret_access_key` | `cache-to`,`cache-from` | String | | See [authentication][1]. |
|
|
| `session_token` | `cache-to`,`cache-from` | String | | See [authentication][1]. |
|
|
| `mode` | `cache-to` | `min`,`max` | `min` | Cache layers to export, see [cache mode][2]. |
|
|
| `ignore-error` | `cache-to` | Boolean | `false` | Ignore errors caused by failed cache exports. |
|
|
|
|
[1]: #authentication
|
|
[2]: _index.md#cache-mode
|
|
|
|
## 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 Credentials][3] for details about
|
|
authentication using environment variables and credentials file.
|
|
|
|
[3]: https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials
|
|
|
|
## Further reading
|
|
|
|
For an introduction to caching see [Optimizing builds with cache](../_index.md).
|
|
|
|
For more information on the `s3` cache backend, see the
|
|
[BuildKit README](https://github.com/moby/buildkit#s3-cache-experimental).
|